Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

cli: Rework vm export/import — presets, auto-naming, positional, progress

zqxwcedee895aeb75a
diff --git a/sources/VPhoneCore/VPhoneBundleOps.swift b/sources/VPhoneCore/VPhoneBundleOps.swift
index 33bfc966..31a83110 100644
--- a/sources/VPhoneCore/VPhoneBundleOps.swift
+++ b/sources/VPhoneCore/VPhoneBundleOps.swift
@@ -167,16 +167,23 @@ public enum VPhoneBundleOps {
// MARK: - Export / Import
- /// Compression preset for `export`. All import transparently: `importArchive`
- /// auto-detects the compressor via `tar -tf`/`-xf`. `threads=0` → all cores.
+ /// Compression preset for `export`. Both import transparently — `importArchive`
+ /// auto-detects the compressor when it extracts. `threads=0` → all cores.
public enum ExportCompression: String, CaseIterable, Sendable {
- case fast, balanced, max
+ case fast, max
var tarArgs: [String] {
switch self {
- case .fast: ["--zstd", "--options", "zstd:compression-level=3,zstd:threads=0"]
- case .balanced: ["--zstd", "--options", "zstd:compression-level=19,zstd:threads=0"]
- case .max: ["-J", "--options", "xz:compression-level=9,xz:threads=0"]
+ case .fast: ["--zstd", "--options", "zstd:compression-level=3,zstd:threads=0"]
+ case .max: ["-J", "--options", "xz:compression-level=9,xz:threads=0"]
+ }
+ }
+
+ /// Extension for auto-named output when `export`'s destination is a directory.
+ public var fileExtension: String {
+ switch self {
+ case .fast: "tzst"
+ case .max: "txz"
}
}
}
@@ -187,39 +194,83 @@ public enum VPhoneBundleOps {
/// `Disk.img`). Always excluded.
static let exportExcludePatterns = ["*.vphoned.signed", "*cfw_input*", "*cfw_jb_input*", "*.cfw_temp*"]
+ /// When `to` is an existing directory, the archive is written inside it as
+ /// `<name>.<compression.fileExtension>`. Returns the resolved output URL.
+ ///
+ /// Runs as a two-stage `tar` pipeline (uncompressed producer → compressing
+ /// consumer via bsdtar's `@-`) so `progress` can be driven off the
+ /// uncompressed byte stream: it is called with `(bytesDone, totalBytes)`,
+ /// where `totalBytes` is the bundle's on-disk logical size (minus excludes).
+ @discardableResult
public static func export(
bundleNamed name: String, to outFile: URL, includeIPSW: Bool,
- compression: ExportCompression = .balanced, in library: VPhoneLibrary
- ) throws {
+ compression: ExportCompression = .fast, in library: VPhoneLibrary,
+ progress: ((Int64, Int64) -> Void)? = nil
+ ) throws -> URL {
_ = try library.bundle(named: name) // validate it exists
- var args = ["-cf", outFile.path] + compression.tarArgs
- if !includeIPSW { args += ["--exclude", "*_Restore*"] }
- for pattern in exportExcludePatterns { args += ["--exclude", pattern] }
- args += ["-C", library.root.path, name]
- let r = try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: "/usr/bin/tar"), args)
- guard r.succeeded else { throw VPhoneBundleOpsError.tarFailed(r.stderr) }
+ var isDir: ObjCBool = false
+ let outFile = FileManager.default.fileExists(atPath: outFile.path, isDirectory: &isDir) && isDir.boolValue
+ ? outFile.appendingPathComponent("\(name).\(compression.fileExtension)")
+ : outFile
+
+ // gnutar (not the bsdtar-default pax): pax extended headers make the
+ // consumer's `@-` reader misbid the stream as mtree ("Line too long")
+ // on large members; gnutar also carries files >8 GB (ustar cannot).
+ var producer = ["--format", "gnutar", "-cf", "-"]
+ if !includeIPSW { producer += ["--exclude", "*_Restore*"] }
+ for pattern in exportExcludePatterns { producer += ["--exclude", pattern] }
+ producer += ["-C", library.root.path, name]
+ let consumer = ["-cf", outFile.path] + compression.tarArgs + ["@-"]
+
+ let total = progress != nil
+ ? archivedLogicalSize(bundleDir: library.url(forName: name), libraryRoot: library.root, includeIPSW: includeIPSW)
+ : 0
+ let err = try VPhoneProcessRunner.runCountingTarPipe(
+ producerArgs: producer, sourceFile: nil, consumerArgs: consumer
+ ) { done in progress?(done, total) }
+ if let err { throw VPhoneBundleOpsError.tarFailed(err) }
+ return outFile
}
+ /// On-disk logical size of the members `export` will archive, mirroring the
+ /// tar `--exclude` patterns so the progress total matches the streamed bytes.
+ private static func archivedLogicalSize(
+ bundleDir: URL, libraryRoot: URL, includeIPSW: Bool
+ ) -> Int64 {
+ let fm = FileManager.default
+ guard let en = fm.enumerator(
+ at: bundleDir,
+ includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey]) else { return 0 }
+ let prefix = libraryRoot.path.count + 1 // members are "<name>/..."
+ var total: Int64 = 0
+ for case let url as URL in en {
+ let rel = String(url.path.dropFirst(prefix))
+ if !includeIPSW, rel.contains("_Restore") { en.skipDescendants(); continue }
+ if exportExcludePatterns.contains(where: { fnmatch($0, rel, 0) == 0 }) { continue }
+ guard let vals = try? url.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey]),
+ vals.isRegularFile == true else { continue }
+ total += Int64(vals.fileSize ?? 0)
+ }
+ return total
+ }
+
+ /// Extracts (auto-detecting gzip/zstd/xz) into a private staging dir, then
+ /// promotes the single top-level bundle to the library. Extracting first
+ /// means the archive is decompressed once; `progress` is called with
+ /// `(bytesDone, totalBytes)` as the compressed file is fed into `tar -x`,
+ /// where `totalBytes` is the archive's size on disk.
public static func importArchive(
- from inFile: URL, name: String?, in library: VPhoneLibrary
+ from inFile: URL, name: String?, in library: VPhoneLibrary,
+ progress: ((Int64, Int64) -> Void)? = nil
) throws -> VPhoneBundle {
let fm = FileManager.default
- // Auto-detect the compression (-tf, not -tzf) so both legacy gzip and
- // current xz archives import.
- let listing = try VPhoneProcessRunner.runCapturing(
- URL(fileURLWithPath: "/usr/bin/tar"), ["-tf", inFile.path])
- guard listing.succeeded else { throw VPhoneBundleOpsError.tarFailed(listing.stderr) }
- let topDirs = Set(listing.stdout.split(whereSeparator: \.isNewline).compactMap {
- $0.split(separator: "/").first.map(String.init)
- })
- guard topDirs.count == 1, let archived = topDirs.first else {
- throw VPhoneBundleOpsError.badArchive(
- "expected a single top-level bundle directory, found \(topDirs.sorted())")
+ // Fail fast when the destination name is already known (explicit rename).
+ if let name {
+ try requireValidName(name)
+ if fm.fileExists(atPath: library.url(forName: name).path) {
+ throw VPhoneLibraryError.alreadyExists(name: name)
+ }
}
- let finalName = name ?? archived
- try requireValidName(finalName)
- let dst = library.url(forName: finalName)
- if fm.fileExists(atPath: dst.path) { throw VPhoneLibraryError.alreadyExists(name: finalName) }
// Extract into a private staging dir so the archive's OWN top-level name
// can never clobber/merge into an existing bundle of that name; only the
@@ -229,9 +280,21 @@ public enum VPhoneBundleOps {
try fm.createDirectory(at: staging, withIntermediateDirectories: true)
defer { try? fm.removeItem(at: staging) }
- let extract = try VPhoneProcessRunner.runCapturing(
- URL(fileURLWithPath: "/usr/bin/tar"), ["-xf", inFile.path, "-C", staging.path])
- guard extract.succeeded else { throw VPhoneBundleOpsError.tarFailed(extract.stderr) }
+ let total = progress != nil ? fileByteSize(inFile) : 0
+ let err = try VPhoneProcessRunner.runCountingTarPipe(
+ producerArgs: nil, sourceFile: inFile, consumerArgs: ["-xf", "-", "-C", staging.path]
+ ) { done in progress?(done, total) }
+ if let err { throw VPhoneBundleOpsError.tarFailed(err) }
+
+ let entries = try fm.contentsOfDirectory(atPath: staging.path)
+ guard entries.count == 1, let archived = entries.first else {
+ throw VPhoneBundleOpsError.badArchive(
+ "expected a single top-level bundle directory, found \(entries.sorted())")
+ }
+ let finalName = name ?? archived
+ try requireValidName(finalName)
+ let dst = library.url(forName: finalName)
+ if fm.fileExists(atPath: dst.path) { throw VPhoneLibraryError.alreadyExists(name: finalName) }
let extracted = staging.appendingPathComponent(archived)
guard fm.fileExists(atPath: extracted.appendingPathComponent("config.plist").path) else {
throw VPhoneBundleOpsError.badArchive(
@@ -240,4 +303,9 @@ public enum VPhoneBundleOps {
try fm.moveItem(at: extracted, to: dst)
return try VPhoneBundle.load(at: dst)
}
+
+ private static func fileByteSize(_ url: URL) -> Int64 {
+ let size = (try? url.resourceValues(forKeys: [.fileSizeKey]))?.fileSize
+ return Int64(size ?? 0)
+ }
}
diff --git a/sources/vphone-cli/VPhoneVMTransferCLI.swift b/sources/vphone-cli/VPhoneVMTransferCLI.swift
index c5e2917a..146561ff 100644
--- a/sources/vphone-cli/VPhoneVMTransferCLI.swift
+++ b/sources/vphone-cli/VPhoneVMTransferCLI.swift
@@ -21,8 +21,6 @@ struct VPhoneVMCloneCommand: ParsableCommand {
}
}
-extension VPhoneBundleOps.ExportCompression: ExpressibleByArgument {}
-
struct VPhoneVMExportCommand: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "export", abstract: "Export a VM bundle to a .tgz archive")
@@ -30,16 +28,19 @@ struct VPhoneVMExportCommand: ParsableCommand {
@OptionGroup var lib: VPhoneLibraryOption
@Argument(help: "VM name") var name: String?
@Option(name: .shortAndLong, help: "output archive path") var out: String
- @Option(name: .shortAndLong, help: "compression preset: fast | balanced | max")
- var compress: VPhoneBundleOps.ExportCompression = .balanced
+ @Flag(help: "densest compression (xz -9) instead of the default fast (zstd -3)") var max = false
@Flag(help: "include the *_Restore* IPSW directory") var includeIpsw = false
func run() throws {
let name = try VPhoneVMSelection.resolveExisting(name, in: lib.library)
- try VPhoneBundleOps.export(
+ let compression: VPhoneBundleOps.ExportCompression = max ? .max : .fast
+ let bar = VPhoneProgressBar(label: "exporting \(name)")
+ let outURL = try VPhoneBundleOps.export(
bundleNamed: name, to: URL(fileURLWithPath: out), includeIPSW: includeIpsw,
- compression: compress, in: lib.library)
- print("exported \(name) → \(out)")
+ compression: compression, in: lib.library,
+ progress: { done, total in bar.update(done: done, total: total) })
+ bar.finish()
+ print("exported \(name) → \(outURL.path)")
}
}
@@ -48,12 +49,15 @@ struct VPhoneVMImportCommand: ParsableCommand {
commandName: "import", abstract: "Import a VM bundle from a .tgz archive")
@OptionGroup var lib: VPhoneLibraryOption
- @Option(name: [.customShort("i"), .customLong("in")], help: "input archive path") var input: String
+ @Argument(help: "input archive path") var input: String
@Option(name: .shortAndLong, help: "name for the imported VM (default: the archive's own name)") var name: String?
func run() throws {
+ let bar = VPhoneProgressBar(label: "importing")
let bundle = try VPhoneBundleOps.importArchive(
- from: URL(fileURLWithPath: input), name: name, in: lib.library)
+ from: URL(fileURLWithPath: input), name: name, in: lib.library,
+ progress: { done, total in bar.update(done: done, total: total) })
+ bar.finish()
print("imported → \(bundle.name)")
}
}
diff --git a/tests/VPhoneCoreTests/BundleOpsTests.swift b/tests/VPhoneCoreTests/BundleOpsTests.swift
index 00dda2bd..54e95b81 100644
--- a/tests/VPhoneCoreTests/BundleOpsTests.swift
+++ b/tests/VPhoneCoreTests/BundleOpsTests.swift
@@ -393,7 +393,7 @@ struct BundleOpsTests {
return (archive, imported)
}
- @Test func exportDefaultsToBalancedZstd() throws {
+ @Test func exportDefaultsToFastZstd() throws {
let (archive, imported) = try exportAndImport(nil)
#expect(try magic(archive, 4) == Self.zstdMagic)
#expect(imported.manifest.cpuCount == 6)
@@ -411,11 +411,64 @@ struct BundleOpsTests {
#expect(imported.manifest.cpuCount == 6)
}
+ @Test func exportToDirectoryAutoNamesWithExtension() throws {
+ let root = try makeRoot()
+ let rom = try fakeROM(); let seprom = try fakeROM()
+ let lib = VPhoneLibrary(root: root)
+ _ = try VPhoneBundleOps.create(
+ .init(name: "orig", cpuCount: 6, memoryMB: 2048, diskSizeGB: 1,
+ romSource: rom, sepromSource: seprom), in: lib)
+ let outDir = try makeRoot()
+ let zstdOut = try VPhoneBundleOps.export(
+ bundleNamed: "orig", to: outDir, includeIPSW: false, in: lib)
+ #expect(zstdOut == outDir.appendingPathComponent("orig.tzst"))
+ #expect(FileManager.default.fileExists(atPath: zstdOut.path))
+ let xzOut = try VPhoneBundleOps.export(
+ bundleNamed: "orig", to: outDir, includeIPSW: false, compression: .max, in: lib)
+ #expect(xzOut == outDir.appendingPathComponent("orig.txz"))
+ #expect(FileManager.default.fileExists(atPath: xzOut.path))
+ }
+
+ @Test func exportAndImportReportProgress() throws {
+ final class Collector {
+ private(set) var dones: [Int64] = []
+ private(set) var total: Int64 = 0
+ func add(_ done: Int64, _ total: Int64) { dones.append(done); self.total = total }
+ }
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let rom = try fakeROM(); let seprom = try fakeROM()
+ let lib = VPhoneLibrary(root: root)
+ _ = try VPhoneBundleOps.create(
+ .init(name: "orig", cpuCount: 6, memoryMB: 2048, diskSizeGB: 1,
+ romSource: rom, sepromSource: seprom), in: lib)
+
+ let exp = Collector()
+ let archive = root.appendingPathComponent("orig.tzst")
+ try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib) {
+ exp.add($0, $1)
+ }
+ #expect(!exp.dones.isEmpty)
+ #expect(exp.total > 0) // bundle logical size
+ #expect(exp.dones.last! > 0)
+ #expect(exp.dones == exp.dones.sorted()) // monotonically non-decreasing
+
+ let imp = Collector()
+ let dstRoot = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: dstRoot) }
+ _ = try VPhoneBundleOps.importArchive(from: archive, name: "copy", in: VPhoneLibrary(root: dstRoot)) {
+ imp.add($0, $1)
+ }
+ let archiveSize = try Data(contentsOf: archive).count
+ #expect(!imp.dones.isEmpty)
+ #expect(imp.total == Int64(archiveSize)) // total == compressed file size
+ #expect(imp.dones.last! == Int64(archiveSize)) // whole archive fed
+ #expect(imp.dones == imp.dones.sorted())
+ }
+
@Test func compressionPresetTarArgs() {
#expect(VPhoneBundleOps.ExportCompression.fast.tarArgs
== ["--zstd", "--options", "zstd:compression-level=3,zstd:threads=0"])
- #expect(VPhoneBundleOps.ExportCompression.balanced.tarArgs
- == ["--zstd", "--options", "zstd:compression-level=19,zstd:threads=0"])
#expect(VPhoneBundleOps.ExportCompression.max.tarArgs
== ["-J", "--options", "xz:compression-level=9,xz:threads=0"])
}