tart run: introduce --disk option (#156)

* tart run: introduce --disk option

* Document how to create disks using Disk Utility

README.md

@@ -55,6 +55,31 @@ config from above will just work in Cirrus CI and your tasks will be executed in
 
 **Note:** Cirrus CI only allows [images managed and regularly updated by us](https://github.com/orgs/cirruslabs/packages?tab=packages&q=macos).
 
+### Retrieving artifacts from within Tart VMs
+
+In many cases there is a need to retrieve particular files or a folder from within a Tart virtual machine.
+For example, the below `.cirrus.yml` configuration defines a single task that builds a `tart` binary and
+exposes it via [`artifacts` instruction](https://cirrus-ci.org/guide/writing-tasks/#artifacts-instruction):
+
+```yaml
+task:
+  name: Build
+  macos_instance:
+    image: ghcr.io/cirruslabs/macos-monterey-xcode:latest
+  build_script: swift build --product tart
+  binary_artifacts:
+    path: .build/debug/tart
+```
+
+Running Cirrus CLI with `--artifacts-dir` will write defined `artifacts` to the provided local directory on the host:
+
+```bash
+cirrus run --artifacts-dir artifacts
+```
+
+Note that all retrieved artifacts will be prefixed with the associated task name and `artifacts` instruction name.
+For the example above, `tart` binary will be saved to `$PWD/artifacts/Build/binary/.build/debug/tart`.
+
 ## Virtual Machine Management
 
 ### Creating from scratch

Sources/tart/Commands/Run.swift

@@ -24,51 +24,79 @@ struct Run: AsyncParsableCommand {
   
   @Flag(help: ArgumentHelp(
           "Use screen sharing instead of the built-in UI.",
-          discussion: "Useful since VNC supports copy/paste, drag and drop, etc.\nNote that Remote Login option should be enabled inside the VM.")) 
+          discussion: "Useful since Screen Sharing supports copy/paste, drag and drop, etc.\n"
+            + "Note that Remote Login option should be enabled inside the VM."))
   var vnc: Bool = false
 
+  @Flag(help: ArgumentHelp(
+    "Use Virtualization.Framework's VNC server instead of the build-in UI.",
+    discussion: "Useful since this type of VNC is available in recovery mode and in macOS installation.\n"
+      + "Note that this feature is experimental and there may be bugs present when using VNC."))
+  var vncExperimental: Bool = false
+
   @Flag var withSoftnet: Bool = false
 
-  @MainActor
-  func run() async throws {    
-    let vmDir = try VMStorageLocal().open(name)
-    vm = try VM(vmDir: vmDir, withSoftnet: withSoftnet)
+  @Option(help: ArgumentHelp("""
+    Additional disk attachments with an optional read-only specifier\n(e.g. --disk=\"disk.bin\" --disk=\"disk.bin:ro\")
+    """, discussion: """
+    Learn how to create a disk image using Disk Utility here:
+    https://support.apple.com/en-gb/guide/disk-utility/dskutl11888/mac
+    """))
+  var disk: [String] = []
 
-    var vncWrapper: VNCWrapper?
-
-    if vnc {
-        vncWrapper = VNCWrapper(virtualMachine: vm!.virtualMachine)
+  func validate() throws {
+    if vnc && vncExperimental {
+      throw ValidationError("--vnc and --vnc-experimental are mutually exclusive")
     }
+  }
+
+  @MainActor
+  func run() async throws {
+    let vmDir = try VMStorageLocal().open(name)
+    vm = try VM(
+      vmDir: vmDir,
+      withSoftnet: withSoftnet,
+      additionalDiskAttachments: additionalDiskAttachments()
+    )
+
+    let vncImpl: VNC? = try {
+      if vnc {
+        let vmConfig = try VMConfig.init(fromURL: vmDir.configURL)
+        return ScreenSharingVNC(vmConfig: vmConfig)
+      } else if vncExperimental {
+        return FullFledgedVNC(virtualMachine: vm!.virtualMachine)
+      } else {
+        return nil
+      }
+    }()
 
     let task = Task {
       do {
-        if let vncWrapper = vncWrapper {
-          let port = try await vncWrapper.waitForPort()
-
-          let url = URL(string: "vnc://:\(vncWrapper.password)@127.0.0.1:\(port)")!
+        if let vncImpl = vncImpl {
+          let vncURL = try await vncImpl.waitForURL()
 
           if noGraphics || ProcessInfo.processInfo.environment["CI"] != nil {
-            print("VNC server is running at \(url)")
+            print("VNC server is running at \(vncURL)")
           } else {
-            print("Opening \(url)...")
-            NSWorkspace.shared.open(url)
+            print("Opening \(vncURL)...")
+            NSWorkspace.shared.open(vncURL)
           }
         }
 
         try await vm!.run(recovery)
 
-        if let vncWrapper = vncWrapper {
-          try vncWrapper.stop()
+        if let vncImpl = vncImpl {
+          try vncImpl.stop()
         }
 
         Foundation.exit(0)
       } catch {
         if error.localizedDescription.contains("Failed to lock auxiliary storage.") {
           print("Virtual machine \"\(name)\" is already running!")
-        } else {
-          print(error)
+          Foundation.exit(2)
         }
 
+        print(error)
         Foundation.exit(1)
       }
     }
@@ -79,13 +107,34 @@ struct Run: AsyncParsableCommand {
     }
     sigintSrc.activate()
 
-    if noGraphics || vnc {
+    if noGraphics || vnc || vncExperimental {
       dispatchMain()
     } else {
       runUI()
     }
   }
 
+  func additionalDiskAttachments() throws -> [VZDiskImageStorageDeviceAttachment] {
+    var result: [VZDiskImageStorageDeviceAttachment] = []
+    let readOnlySuffix = ":ro"
+
+    for rawDisk in disk {
+      if rawDisk.hasSuffix(readOnlySuffix) {
+        result.append(try VZDiskImageStorageDeviceAttachment(
+          url: URL(fileURLWithPath: String(rawDisk.prefix(rawDisk.count - readOnlySuffix.count))),
+          readOnly: true
+        ))
+      } else {
+        result.append(try VZDiskImageStorageDeviceAttachment(
+          url: URL(fileURLWithPath: rawDisk),
+          readOnly: false
+        ))
+      }
+    }
+
+    return result
+  }
+
   private func runUI() {
     let nsApp = NSApplication.shared
     nsApp.setActivationPolicy(.regular)

Sources/tart/Config.swift

@@ -1,11 +1,23 @@
 import Foundation
 
 struct Config {
-  public static let tartHomeDir: URL = FileManager.default
-          .homeDirectoryForCurrentUser
-          .appendingPathComponent(".tart", isDirectory: true)
+  let tartHomeDir: URL
+  let tartCacheDir: URL
 
-  public static let tartCacheDir: URL = tartHomeDir.appendingPathComponent("cache", isDirectory: true)
+  init() {
+    var tartHomeDir: URL
+
+    if let customTartHome = ProcessInfo.processInfo.environment["TART_HOME"] {
+      tartHomeDir = URL(fileURLWithPath: customTartHome)
+    } else {
+      tartHomeDir = FileManager.default
+              .homeDirectoryForCurrentUser
+              .appendingPathComponent(".tart", isDirectory: true)
+    }
+
+    self.tartHomeDir = tartHomeDir
+    tartCacheDir = tartHomeDir.appendingPathComponent("cache", isDirectory: true)
+  }
 
   static func jsonEncoder() -> JSONEncoder {
     let encoder = JSONEncoder()

Sources/tart/Credentials/KeychainCredentialsProvider.swift

@@ -34,21 +34,34 @@ class KeychainCredentialsProvider: CredentialsProvider {
     }
 
     func store(host: String, user: String, password: String) throws {
+        let passwordData = password.data(using: .utf8)
         let attributes: [String: Any] = [kSecClass as String: kSecClassInternetPassword,
                                          kSecAttrAccount as String: user,
                                          kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
                                          kSecAttrServer as String: host,
-                                         kSecValueData as String: password,
+                                         kSecValueData as String: passwordData,
                                          kSecAttrLabel as String: "Tart Credentials",
         ]
 
         let status = SecItemAdd(attributes as CFDictionary, nil)
 
         switch status {
-        case errSecSuccess, errSecDuplicateItem:
+        case errSecSuccess:
             return
+        case errSecDuplicateItem:
+            let status = SecItemUpdate(attributes as CFDictionary,
+                [kSecValueData as String : passwordData] as CFDictionary)
+            if status != errSecSuccess {
+              throw CredentialsProviderError.Failed(message: "Keychain failed to update item: \(status.explanation())")
+            }
         default:
-            throw CredentialsProviderError.Failed(message: "Keychain returned unsuccessful status \(status)")
+            throw CredentialsProviderError.Failed(message: "Keychain failed to add item: \(status.explanation())")
         }
     }
 }
+
+extension OSStatus {
+  func explanation() -> CFString {
+    SecCopyErrorMessageString(self, nil) ?? "Unknown status code \(self)." as CFString
+  }
+}

Sources/tart/VM.swift

@@ -25,7 +25,10 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
 
   var softnet: Softnet? = nil
 
-  init(vmDir: VMDirectory, withSoftnet: Bool = false) throws {
+  init(vmDir: VMDirectory,
+       withSoftnet: Bool = false,
+       additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment] = []
+  ) throws {
     let auxStorage = VZMacAuxiliaryStorage(contentsOf: vmDir.nvramURL)
 
     name = vmDir.name
@@ -37,7 +40,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
 
     let configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL, auxStorage: auxStorage, vmConfig: config,
-      softnet: softnet)
+      softnet: softnet, additionalDiskAttachments: additionalDiskAttachments)
     virtualMachine = VZVirtualMachine(configuration: configuration)
 
     super.init()
@@ -53,7 +56,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
 
 
-    let ipswCacheFolder = Config.tartCacheDir.appendingPathComponent("IPSWs", isDirectory: true)
+    let ipswCacheFolder = Config().tartCacheDir.appendingPathComponent("IPSWs", isDirectory: true)
     try FileManager.default.createDirectory(at: ipswCacheFolder, withIntermediateDirectories: true)
 
     let expectedIPSWLocation = ipswCacheFolder.appendingPathComponent("\(image.buildVersion).ipsw", isDirectory: false)
@@ -94,7 +97,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
   }
 
-  init(vmDir: VMDirectory, ipswURL: URL?, diskSizeGB: UInt16, withSoftnet: Bool = false) async throws {
+  init(
+    vmDir: VMDirectory,
+    ipswURL: URL?,
+    diskSizeGB: UInt16,
+    withSoftnet: Bool = false,
+    additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment] = []
+  ) async throws {
     let ipswURL = ipswURL != nil ? ipswURL! : try await VM.retrieveLatestIPSW();
 
     // Load the restore image and try to get the requirements
@@ -132,7 +141,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
 
     let configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL, auxStorage: auxStorage, vmConfig: config,
-      softnet: softnet)
+      softnet: softnet, additionalDiskAttachments: additionalDiskAttachments)
     virtualMachine = VZVirtualMachine(configuration: configuration)
 
     super.init()
@@ -183,7 +192,8 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     diskURL: URL,
     auxStorage: VZMacAuxiliaryStorage,
     vmConfig: VMConfig,
-    softnet: Softnet? = nil
+    softnet: Softnet? = nil,
+    additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment]
   ) throws -> VZVirtualMachineConfiguration {
     let configuration = VZVirtualMachineConfiguration()
 
@@ -247,9 +257,9 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     configuration.networkDevices = [vio]
 
     // Storage
-    let attachment = try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false)
-    let storage = VZVirtioBlockDeviceConfiguration(attachment: attachment)
-    configuration.storageDevices = [storage]
+    var attachments = [try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false)]
+    attachments.append(contentsOf: additionalDiskAttachments)
+    configuration.storageDevices = attachments.map { VZVirtioBlockDeviceConfiguration(attachment: $0) }
 
     // Entropy
     configuration.entropyDevices = [VZVirtioEntropyDeviceConfiguration()]

Sources/tart/VMStorageLocal.swift

@@ -1,7 +1,7 @@
 import Foundation
 
 class VMStorageLocal {
-  let baseURL: URL = Config.tartHomeDir.appendingPathComponent("vms", isDirectory: true)
+  let baseURL: URL = Config().tartHomeDir.appendingPathComponent("vms", isDirectory: true)
 
   private func vmURL(_ name: String) -> URL {
     baseURL.appendingPathComponent(name, isDirectory: true)

Sources/tart/VMStorageOCI.swift

@@ -1,7 +1,7 @@
 import Foundation
 
 class VMStorageOCI {
-  let baseURL = Config.tartCacheDir.appendingPathComponent("OCIs", isDirectory: true)
+  let baseURL = Config().tartCacheDir.appendingPathComponent("OCIs", isDirectory: true)
 
   private func vmURL(_ name: RemoteName) -> URL {
     baseURL.appendingRemoteName(name)

Sources/tart/VNC/FullFledgedVNC.swift

@@ -2,7 +2,7 @@ import Foundation
 import Dynamic
 import Virtualization
 
-class VNCWrapper {
+class FullFledgedVNC: VNC {
     let password: String
     private let vnc: Dynamic
 
@@ -15,6 +15,19 @@ class VNCWrapper {
         vnc.start()
     }
 
+    func waitForURL() async throws -> URL {
+      while true {
+        // Port is 0 shortly after start(),
+        // but will be initialized later
+        if let port = vnc.port.asUInt16, port != 0 {
+          return URL(string: "vnc://:\(password)@127.0.0.1:\(port)")!
+        }
+
+        // Wait 50 ms.
+        try await Task.sleep(nanoseconds: 50_000_000)
+      }
+    }
+
     func stop() throws {
         vnc.stop()
     }
@@ -22,17 +35,4 @@ class VNCWrapper {
     deinit {
         try? stop()
     }
-
-    func waitForPort() async throws -> UInt16 {
-        while true {
-            // Port is 0 shortly after start(),
-            // but will be initialized later
-            if let port = vnc.port.asUInt16, port != 0 {
-                return port
-            }
-
-            // Wait 50 ms.
-            try await Task.sleep(nanoseconds: 50_000_000)
-        }
-    }
 }

Sources/tart/VNC/ScreenSharingVNC.swift

@@ -0,0 +1,25 @@
+import Foundation
+import Dynamic
+import Virtualization
+
+class ScreenSharingVNC: VNC {
+  let vmConfig: VMConfig
+
+  init(vmConfig: VMConfig) {
+    self.vmConfig = vmConfig
+  }
+
+  func waitForURL() async throws -> URL {
+    let ip = try await IP.resolveIP(vmConfig, secondsToWait: 60)
+
+    if let ip = ip {
+      return URL(string: "vnc://\(ip)")!
+    }
+
+    throw IPNotFound()
+  }
+
+  func stop() throws {
+    // nothing to do
+  }
+}

Sources/tart/VNC/VNC.swift

@@ -0,0 +1,6 @@
+import Foundation
+
+protocol VNC {
+  func waitForURL() async throws -> URL
+  func stop() throws
+}