Adopt swift-log

Package.swift

@@ -126,6 +126,10 @@ let package = Package(
             url: "https://github.com/stackotter/swift-benchmark",
             .upToNextMinor(from: "0.2.0")
         ),
+        .package(
+            url: "https://github.com/apple/swift-log.git",
+            from: "1.8.0"
+        ),
         // .package(
         //     url: "https://github.com/stackotter/TermKit",
         //     revision: "163afa64f1257a0c026cc83ed8bc47a5f8fc9704"
@@ -145,6 +149,7 @@ let package = Package(
             dependencies: [
                 "HotReloadingMacrosPlugin",
                 .product(name: "ImageFormats", package: "swift-image-formats"),
+                .product(name: "Logging", package: "swift-log"),
             ],
             exclude: [
                 "Builders/ViewBuilder.swift.gyb",

Sources/SwiftCrossUI/App.swift

@@ -1,4 +1,23 @@
 import Foundation
+import Logging
+
+/// The global logger.
+///
+/// `nil` if the logger hasn't been set yet (which is only the case during
+/// ``App/init()``).
+///
+/// > Safety: This is only ever set in one place, namely in ``App/main()``.
+private nonisolated(unsafe) var _logger: Logger?
+
+/// The global logger.
+///
+/// This is safe to use from anywhere in the library (except in
+/// `extractSwiftBundlerMetadata()`, since that's called before the logger is
+/// initialized -- this property will fatal-error in that case).
+var logger: Logger {
+    guard let _logger else { fatalError("logger not yet initialized") }
+    return _logger
+}
 
 /// An application.
 @MainActor
@@ -8,9 +27,11 @@ public protocol App {
     /// The type of scene representing the content of the app.
     associatedtype Body: Scene
 
-    /// Metadata loaded at app start up. By default SwiftCrossUI attempts
-    /// to load metadata inserted by Swift Bundler if present. Used by backends'
-    /// default ``App/backend`` implementations if not `nil`.
+    /// Metadata loaded at app start up.
+    ///
+    /// By default SwiftCrossUI attempts to load metadata inserted by Swift
+    /// Bundler if present. Used by backends' default ``App/backend``
+    /// implementations if not `nil`.
     static var metadata: AppMetadata? { get }
 
     /// The application's backend.
@@ -20,6 +41,9 @@ public protocol App {
     @SceneBuilder var body: Body { get }
 
     /// Creates an instance of the app.
+    ///
+    /// This initializer is run before anything else, so you can perform early
+    /// setup tasks in here, such as [setting the logging backend](doc:Logging).
     init()
 }
 
@@ -28,7 +52,9 @@ public protocol App {
 @MainActor
 public var _forceRefresh: () -> Void = {}
 
-/// Metadata embedded by Swift Bundler if present. Loaded at app start up.
+/// Metadata embedded by Swift Bundler, if present. Loaded at app start up.
+///
+/// This is accessible from within ``App/init()``.
 @MainActor
 private var swiftBundlerAppMetadata: AppMetadata?
 
@@ -52,6 +78,8 @@ private enum SwiftBundlerMetadataError: LocalizedError {
 
 extension App {
     /// Metadata loaded at app start up.
+    ///
+    /// This is accessible from within ``init()``.
     public static var metadata: AppMetadata? {
         swiftBundlerAppMetadata
     }
@@ -61,6 +89,11 @@ extension App {
         swiftBundlerAppMetadata = extractSwiftBundlerMetadata()
 
         let app = Self()
+
+        // set up the logger _after_ calling App's initializer; that way users
+        // can call LoggingSystem.bootstrap in the init
+        _logger = Logger(label: "SwiftCrossUI")
+
         let _app = _App(app)
         _forceRefresh = {
             app.backend.runInMainThread {
@@ -71,13 +104,16 @@ extension App {
     }
 
     private static func extractSwiftBundlerMetadata() -> AppMetadata? {
+        // NB: the logger hasn't been set up yet when this is called, so we're
+        // forced to rely on good ol' `print`
+
         guard let executable = Bundle.main.executableURL else {
-            print("warning: No executable url")
+            print("warning: no executable url")
             return nil
         }
 
         guard let data = try? Data(contentsOf: executable) else {
-            print("warning: Executable failed to read self (to extract metadata)")
+            print("warning: executable failed to read itself (to extract metadata)")
             return nil
         }
 
@@ -115,7 +151,7 @@ extension App {
                 additionalMetadata: additionalMetadata
             )
         } catch {
-            print("warning: Swift Bundler metadata present but couldn't be parsed")
+            print("warning: swift-bundler metadata present but couldn't be parsed")
             print("  -> \(error)")
             return nil
         }

Sources/SwiftCrossUI/Backend/AppBackend.swift

@@ -801,15 +801,15 @@ extension AppBackend {
 extension AppBackend {
     /// Used by placeholder implementations of backend methods.
     private func todo(_ function: String = #function) -> Never {
-        print("\(type(of: self)): \(function) not implemented")
+        logger.critical("\(type(of: self)): \(function) not implemented")
         Foundation.exit(1)
     }
 
     private func ignored(_ function: String = #function) {
         #if DEBUG
-            print(
-                "\(type(of: self)): \(function) is being ignored\nConsult at the documentation for further information."
-            )
+        logger.warning(
+            "\(type(of: self)): \(function) is being ignored; consult the documentation for further information"
+        )
         #endif
     }
 

Sources/SwiftCrossUI/Environment/Actions/DismissAction.swift

@@ -38,7 +38,7 @@ private struct DismissActionKey: EnvironmentKey {
     static var defaultValue: DismissAction {
         DismissAction(action: {
             #if DEBUG
-                print("warning: dismiss() called but no presentation context is available")
+                logger.warning("dismiss() called but no presentation context is available")
             #endif
         })
     }

Sources/SwiftCrossUI/Environment/Actions/OpenURLAction.swift

@@ -11,7 +11,10 @@ public struct OpenURLAction {
             do {
                 try backend.openExternalURL(url)
             } catch {
-                print("warning: Failed to open external url: \(error)")
+                logger.warning("failed to open external url", metadata: [
+                    "url": "\(url)",
+                    "error": "\(error)",
+                ])
             }
         }
     }

Sources/SwiftCrossUI/Environment/Actions/RevealFileAction.swift

@@ -15,7 +15,10 @@ public struct RevealFileAction {
             do {
                 try backend.revealFile(file)
             } catch {
-                print("warning: Failed to reveal file: \(error)")
+                logger.warning("failed to reveal file", metadata: [
+                    "url": "\(file)",
+                    "error": "\(error)",
+                ])
             }
         }
     }

Sources/SwiftCrossUI/Environment/EnvironmentValues.swift

@@ -118,7 +118,7 @@ public struct EnvironmentValues {
             backend.activate(window: window as! Backend.Window)
         }
         activate(with: backend)
-        print("Activated")
+        logger.info("window activated")
     }
 
     /// The backend's representation of the window that the current view is

Sources/SwiftCrossUI/Layout/LayoutSystem.swift

@@ -152,11 +152,11 @@ public enum LayoutSystem {
                     dryRun: dryRun
                 )
                 if result.participatesInStackLayouts {
-                    print(
-                        """
-                        warning: Hidden view became visible on second update. \
-                        Layout may break. View: \(child.tag ?? "<unknown type>")
-                        """
+                    logger.warning(
+                        "hidden view became visible on second update; layout may break",
+                        metadata: [
+                            "view": "\(child.tag ?? "<unknown type>")"
+                        ]
                     )
                 }
                 renderedChildren[index] = result

Sources/SwiftCrossUI/Scenes/WindowGroupNode.swift

@@ -200,14 +200,16 @@ public final class WindowGroupNode<Content: View>: SceneGraphNode {
         // backend so I think this is a fine solution for now (people should
         // only use Gtk3Backend if they can't use GtkBackend).
         if let dryRunResult, finalContentResult.size != dryRunResult.size {
-            print(
-                """
-                warning: Final window content size didn't match dry-run size. This is a sign that
-                         either view size caching is broken or that backend.naturalSize(of:) is 
-                         broken (or both).
-                      -> dryRunResult.size:       \(dryRunResult.size)
-                      -> finalContentResult.size: \(finalContentResult.size)
-                """
+            logger.warning(
+                 """
+                 final window content size didn't match dry-run size; this is a sign that \
+                 either view size caching is broken or that backend.naturalSize(of:) is \
+                 broken (or both)
+                 """,
+                metadata: [
+                    "dryRunResult.size": "\(dryRunResult.size)",
+                    "finalContentResult.size": "\(finalContentResult.size)",
+                ]
             )
 
             // Give the view graph one more chance to sort itself out to fail

Sources/SwiftCrossUI/SwiftCrossUI.docc/Logging.md

@@ -0,0 +1,17 @@
+# Logging
+
+SwiftCrossUI's logging mechanism
+
+SwiftCrossUI uses [swift-log](https://github.com/apple/swift-log) for logging
+warnings. By default, it will log messages to the console; however, you can
+use any swift-log backend you want.
+
+To do so, add your backend of choice to your package dependencies, then call
+`LoggingSystem.bootstrap(_:)` in your ``App``'s initializer. This initializer
+is called before anything else happens, so you can also perform other early
+setup tasks in here.
+
+> Important: Calling `LoggingSystem.bootstrap(_:)` anywhere outside of
+> ``App/init()`` will not correctly set the logging backend for SwiftCrossUI, as
+> the library's internal logger is set up immediately after the initializer
+> returns.

Sources/SwiftCrossUI/SwiftCrossUI.docc/SwiftCrossUI.md

@@ -51,5 +51,6 @@ SwiftCrossUI takes inspiration from SwiftUI, allowing you to use the basic conce
 
 ### Other
 
+- <doc:Logging>
 - <doc:Implementation-details>
 - <doc:Deprecated>

Sources/SwiftCrossUI/Values/TextStyle.swift

@@ -52,17 +52,12 @@ extension Font.TextStyle {
     /// specify a text style for a specific platform.
     public func resolve(for deviceClass: DeviceClass) -> Resolved {
         guard let textStyles = Self.resolvedTextStyles[deviceClass] else {
-            print("warning: Missing text styles for device class \(deviceClass)")
+            logger.warning("missing text styles for device class \(deviceClass)")
             return .fallback
         }
 
         guard let textStyle = textStyles[self] else {
-            print(
-                """
-                warning: Missing \(self) text style for device class \
-                \(deviceClass)
-                """
-            )
+            logger.warning("missing \(self) text style for device class \(deviceClass)")
             return .fallback
         }
 

Sources/SwiftCrossUI/ViewGraph/ViewGraphNode.swift

@@ -105,13 +105,11 @@ public class ViewGraphNode<NodeView: View, Backend: AppBackend>: Sendable {
         let mirror = Mirror(reflecting: view)
         for property in mirror.children {
             if property.label == "state" && property.value is ObservableObject {
-                print(
+                logger.warning(
                     """
-
-                    warning: The View.state protocol requirement has been removed in favour of
-                             SwiftUI-style @State annotations. Decorate \(NodeView.self).state
-                             with the @State property wrapper to restore previous behaviour.
-
+                    the View.state protocol requirement has been removed in favour of \
+                    SwiftUI-style @State annotations; decorate \(NodeView.self).state \
+                    with the @State property wrapper to restore previous behaviour
                     """
                 )
             }
@@ -154,13 +152,12 @@ public class ViewGraphNode<NodeView: View, Backend: AppBackend>: Sendable {
                 dryRun: false
             )
             if finalResult.size != newResult.size {
-                print(
-                    """
-                    warning: State-triggered view update had mismatch \
-                    between dry-run size and final size.
-                          -> dry-run size: \(newResult.size)
-                          -> final size:   \(finalResult.size)
-                    """
+                logger.warning(
+                    "state-triggered view update had mismatch between dry-run size and final size",
+                    metadata: [
+                        "dry-run size": "\(newResult.size)",
+                        "final size": "\(finalResult.size)",
+                    ]
                 )
             }
             self.currentResult = finalResult

Sources/SwiftCrossUI/_App.swift

@@ -55,13 +55,11 @@ class _App<AppRoot: App> {
             let mirror = Mirror(reflecting: self.app)
             for property in mirror.children {
                 if property.label == "state" && property.value is ObservableObject {
-                    print(
+                    logger.warning(
                         """
-
-                        warning: The App.state protocol requirement has been removed in favour of
-                                 SwiftUI-style @State annotations. Decorate \(AppRoot.self).state
-                                 with the @State property wrapper to restore previous behaviour.
-
+                        the App.state protocol requirement has been removed in favour of \
+                        SwiftUI-style @State annotations; decorate \(AppRoot.self).state \
+                        with the @State property wrapper to restore previous behaviour
                         """
                     )
                 }