feat(mac-crafter): New logging.

- Write to standard output in terminal environment.
- Write to unified logging system.
- Write to log file.
- All simultaneously.
- Standard output and errors from child processes launched are captured, too.

Signed-off-by: Iva Horn <[email protected]>

Author: i2h3

admin/osx/mac-crafter/README.md

@@ -2,7 +2,7 @@
   - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
   - SPDX-License-Identifier: GPL-2.0-or-later
 -->
-# Mac Crafter
+# mac-crafter
 
 mac-crafter is a tool to easily build a fully functional Nextcloud Desktop Client for macOS.
 It automates cloning, configuring, crafting, codesigning, packaging, and even disk image creation of the client.
@@ -58,6 +58,12 @@ Additional preparation is necessary, though.
 6. Navigate to the "Options" tab.
 7. Enable and define a custom working directory. The root of this Swift package, to be specific. 
 
+## Troubleshooting
+
+mac-crafter has its own simple logging facility which writes to standard output in a terminal environment, the unified logging system of macOS and a log file simultaneously.
+You can stream the log messages in the Console app of macOS by searching for the "mac-crafter" process and "Log" subsystem.
+Alternatively, you can follow the latest log file created in `~/Library/Logs/mac-crafter`.
+
 ## License
 
 Distributed under the terms of the GPL-2.0-or-later license.

admin/osx/mac-crafter/Sources/Commands/Build.swift

@@ -123,7 +123,7 @@ struct Build: AsyncParsableCommand {
     mutating func run() async throws {
         let stopwatch = Stopwatch()
 
-        print("Ensuring build dependencies are met...")
+        Log.info("Ensuring build dependencies are met...")
         stopwatch.record("Build Dependencies")
 
         if codeSignIdentity != nil {
@@ -142,7 +142,7 @@ struct Build: AsyncParsableCommand {
         try await installIfMissing("inkscape", "brew install inkscape")
         try await installIfMissing("python3", "brew install pyenv && pyenv install 3.12.4")
 
-        print("Build dependencies are installed.")
+        Log.info("Build dependencies are installed.")
 
         let fm = FileManager.default
         let buildURL = URL(fileURLWithPath: buildPath).standardized
@@ -157,15 +157,15 @@ struct Build: AsyncParsableCommand {
             stopwatch.record("KDE Craft Setup")
 
             if fm.fileExists(atPath: craftMasterDir.path) {
-                print("KDE Craft is already cloned.")
+                Log.info("KDE Craft is already cloned.")
             } else {
-                print("Cloning KDE Craft...")
+                Log.info("Cloning KDE Craft...")
                 guard await shell("\(gitCloneCommand) \(craftMasterGitUrl) \(craftMasterDir.path)") == 0 else {
                     throw MacCrafterError.gitError("The referenced CraftMaster repository could not be cloned from \(craftMasterGitUrl) to \(craftMasterDir.path)")
                 }
             }
 
-            print("Configuring required KDE Craft blueprint repositories...")
+            Log.info("Configuring required KDE Craft blueprint repositories...")
             stopwatch.record("Craft Blueprints Configuration")
 
             guard await shell("\(craftCommand) --add-blueprint-repository '\(kdeBlueprintsGitUrl)|\(kdeBlueprintsGitRef)|'") == 0 else {
@@ -176,21 +176,21 @@ struct Build: AsyncParsableCommand {
                 throw MacCrafterError.craftError("Error adding Nextcloud Client blueprint repository.")
             }
 
-            print("Crafting KDE Craft...")
+            Log.info("Crafting KDE Craft...")
             stopwatch.record("Craft Crafting")
 
             guard await shell("\(craftCommand) craft") == 0 else {
                 throw MacCrafterError.craftError("Error crafting KDE Craft.")
             }
 
-            print("Crafting Nextcloud Desktop Client dependencies...")
+            Log.info("Crafting Nextcloud Desktop Client dependencies...")
             stopwatch.record("Nextcloud Client Dependencies Crafting")
 
             guard await shell("\(craftCommand) --install-deps \(craftBlueprintName)") == 0 else {
                 throw MacCrafterError.craftError("Error installing dependencies.")
             }
         } else {
-            print("Skipping KDE Craft configuration because it is already and no reconfiguration was requested.")
+            Log.info("Skipping KDE Craft configuration because it is already and no reconfiguration was requested.")
         }
 
         var craftOptions = [
@@ -212,7 +212,7 @@ struct Build: AsyncParsableCommand {
         }
 
         if disableAutoUpdater == false {
-            print("Configuring Sparkle auto-updater.")
+            Log.info("Configuring Sparkle auto-updater.")
 
             stopwatch.record("Sparke Configuration")
 
@@ -233,12 +233,12 @@ struct Build: AsyncParsableCommand {
             .appendingPathComponent("build")
             .appendingPathComponent(craftBlueprintName)
 
-        print("Crafting \(appName) Desktop Client...")
+        Log.info("Crafting \(appName) Desktop Client...")
         stopwatch.record("Desktop Client Crafting")
 
         if fullRebuild {
             if fm.fileExists(atPath: clientBuildURL.path) {
-                print("Removing existing client build directory at: \(clientBuildURL.path)")
+                Log.info("Removing existing client build directory at: \(clientBuildURL.path)")
 
                 do {
                     try fm.removeItem(atPath: clientBuildURL.path)
@@ -258,11 +258,11 @@ struct Build: AsyncParsableCommand {
                 .appendingPathComponent("MacOSX")
 
             if fm.fileExists(atPath: shellIntegrationURL.path) {
-                print("Removing existing shell integration build artifacts...")
+                Log.info("Removing existing shell integration build artifacts...")
                 do {
                     try fm.removeItem(atPath: shellIntegrationURL.path)
                 } catch let error {
-                    print("ERROR: Error removing shell integration build directory: \(error)")
+                    Log.error("Failed to remove shell integration build directory: \(error)")
                     throw MacCrafterError.craftError("Failed to remove existing shell integration build directory!")
                 }
             }
@@ -282,7 +282,7 @@ struct Build: AsyncParsableCommand {
             .appendingPathComponent("\(appName).app")
 
         if let codeSignIdentity {
-            print("Signing Nextcloud Desktop Client libraries and frameworks...")
+            Log.info("Signing Nextcloud Desktop Client libraries and frameworks...")
             stopwatch.record("Code Signing")
 
             let appEntitlements = clientBuildURL
@@ -307,16 +307,16 @@ struct Build: AsyncParsableCommand {
 
             for file in entitlements.values {
                 if FileManager.default.fileExists(atPath: file.path) {
-                    print("Using entitlement manifest: \(file.path)")
+                    Log.info("Using entitlement manifest: \(file.path)")
                 } else {
-                    print("ERROR: Entitlement manifest does not exist: \(file.path)")
+                    Log.error("Entitlement manifest does not exist: \(file.path)")
                 }
             }
 
             try await Signer.signMainBundle(at: clientAppURL, codeSignIdentity: codeSignIdentity, entitlements: entitlements)
         }
 
-        print("Placing Nextcloud Desktop Client in \(productPath)...")
+        Log.info("Placing Nextcloud Desktop Client in \(productPath)...")
 
         if !fm.fileExists(atPath: productPath) {
             try fm.createDirectory(atPath: productPath, withIntermediateDirectories: true, attributes: nil)
@@ -345,7 +345,7 @@ struct Build: AsyncParsableCommand {
             )
         }
 
-        print("Done!")
-        print(stopwatch.report())
+        Log.info("Done!")
+        Log.info(stopwatch.report())
     }
 }

admin/osx/mac-crafter/Sources/Log.swift

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: Nextcloud GmbH
+// SPDX-FileCopyrightText: 2026 Iva Horn
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+import Foundation
+import os
+
+///
+/// A simple logging facility for Mac Crafter to abstract terminal output, log file and unified logging system.
+///
+actor Log: Sendable {
+    private static let shared = Log()
+    private let handle: FileHandle?
+    private let logger: Logger
+
+    init() {
+        let manager = FileManager.default
+
+        let directory = try! manager
+            .url(for: .libraryDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
+            .appendingPathComponent("Logs")
+            .appendingPathComponent("mac-crafter")
+
+        if manager.fileExists(atPath: directory.path) == false {
+            try! manager.createDirectory(at: directory, withIntermediateDirectories: true)
+        }
+
+        let file = directory
+            .appendingPathComponent(UUID().uuidString)
+            .appendingPathExtension("log")
+
+        manager.createFile(atPath: file.path, contents: nil)
+
+        print("Writing log file: \(file.path)")
+        handle = try? FileHandle(forWritingTo: file)
+        logger = Logger(subsystem: "Log", category: "")
+        logger.info("Writing log file: \(file.path)")
+    }
+
+    private func log(level: OSLogType, message: String) {
+        guard message.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false else {
+            return
+        }
+
+        print(message)
+        logger.log(level: level, "\(message, privacy: .public)")
+
+        guard let handle else {
+            return
+        }
+
+        guard let data = "\(message)\n".data(using: .utf8) else {
+            return
+        }
+
+        try? handle.write(contentsOf: data)
+    }
+
+    ///
+    /// Write an informative message.
+    ///
+    static func info(_ message: String) {
+        Task {
+            await shared.log(level: .info, message: message)
+        }
+    }
+
+    ///
+    /// Write an error message.
+    ///
+    static func error(_ message: String) {
+        Task {
+            await shared.log(level: .error, message: message)
+        }
+    }
+}

admin/osx/mac-crafter/Sources/Utils/Install.swift

@@ -29,12 +29,12 @@ func installIfMissing(
     installCommandEnv: [String: String]? = nil
 ) async throws {
     if await commandExists(command) {
-        print("Required command \"\(command)\" already is installed.")
+        Log.info("Required command \"\(command)\" already is installed.")
     } else {
-        print("Required command \"\(command)\" is missing, installing...")
+        Log.info("Required command \"\(command)\" is missing, installing...")
         guard await shell(installCommand, env: installCommandEnv) == 0 else {
             throw InstallError.failedToInstall("Failed to install \"\(command)\"!")
         }
-        print("\"\(command)\" installed.")
+        Log.info("\"\(command)\" installed.")
     }
 }

admin/osx/mac-crafter/Sources/Utils/Packaging.swift

@@ -24,15 +24,15 @@ fileprivate func buildPackage(appName: String, buildWorkPath: String, productPat
         throw PackagingError.projectNameSettingError("Could not set project name in pkgproj!")
     }
     guard await shell("packagesbuild -v --build-folder \(productPath) -F \(productPath) \(pkgprojPath)") == 0 else {
-        throw PackagingError.packageBuildError("Error building pkg file!")
+        throw PackagingError.packageBuildError("Error building package file!")
     }
     return "\(productPath)/\(packageFile)"
 }
 
 fileprivate func signPackage(packagePath: String, packageSigningId: String) async throws {
     let packagePathNew = "\(packagePath).new"
     guard await shell("productsign --timestamp --sign '\(packageSigningId)' \(packagePath) \(packagePathNew)") == 0 else {
-        throw PackagingError.packageSigningError("Could not sign pkg file!")
+        throw PackagingError.packageSigningError("Could not sign package file!")
     }
     let fm = FileManager.default
     try fm.removeItem(atPath: packagePath)
@@ -76,7 +76,7 @@ func packageAppBundle(
     appleTeamId: String?,
     sparklePackageSignKey: String?
 ) async throws {
-    print("Creating pkg file for client…")
+    Log.info("Creating package file for client…")
     let buildWorkPath = "\(buildPath)/\(craftTarget)/build/\(craftBlueprintName)/work/build"
     let packagePath = try await buildPackage(
         appName: appName,
@@ -85,11 +85,11 @@ func packageAppBundle(
     )
 
     if let packageSigningId {
-        print("Signing pkg with \(packageSigningId)…")
+        Log.info("Signing package with \(packageSigningId)…")
         try await signPackage(packagePath: packagePath, packageSigningId: packageSigningId)
 
         if let appleId, let applePassword, let appleTeamId {
-            print("Notarising pkg with Apple ID \(appleId)…")
+            Log.info("Notarising package with Apple ID \(appleId)…")
             try await notarisePackage(
                 packagePath: packagePath,
                 appleId: appleId,
@@ -99,12 +99,12 @@ func packageAppBundle(
         }
     }
 
-    print("Creating Sparkle TBZ file…")
+    Log.info("Creating Sparkle TBZ file…")
     let sparklePackagePath =
         try await buildSparklePackage(packagePath: packagePath, buildPath: buildPath)
 
     if let sparklePackageSignKey {
-        print("Signing Sparkle TBZ file…")
+        Log.info("Signing Sparkle TBZ file…")
         try await signSparklePackage(
             sparkleTbzPath: sparklePackagePath,
             buildPath: buildPath,
@@ -124,7 +124,7 @@ func createDmgForAppBundle(
     appleTeamId: String?,
     sparklePackageSignKey: String?
 ) async throws {
-    print("Creating disk image for the client…")
+    Log.info("Creating disk image for the client…")
 
     let dmgFilePath = URL(fileURLWithPath: productPath)
         .appendingPathComponent(appName)
@@ -136,11 +136,11 @@ func createDmgForAppBundle(
     }
 
     if let packageSigningId {
-        print("Signing DMG with \(packageSigningId)…")
+        Log.info("Signing disk image with \(packageSigningId)…")
         await Signer.sign(at: URL(fileURLWithPath: dmgFilePath), with: packageSigningId, entitlements: nil)
 
         if let appleId, let applePassword, let appleTeamId {
-            print("Notarising DMG with Apple ID \(appleId)…")
+            Log.info("Notarising disk image with Apple ID \(appleId)…")
 
             try await notarisePackage(
                 packagePath: dmgFilePath,
@@ -151,11 +151,11 @@ func createDmgForAppBundle(
         }
     }
 
-    print("Creating Sparkle TBZ file…")
+    Log.info("Creating Sparkle TBZ file…")
     let sparklePackagePath = try await buildSparklePackage(packagePath: dmgFilePath, buildPath: buildPath)
 
     if let sparklePackageSignKey {
-        print("Signing Sparkle TBZ file…")
+        Log.info("Signing Sparkle TBZ file…")
 
         try await signSparklePackage(
             sparkleTbzPath: sparklePackagePath,