Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Trim template System volumes offline and keep templates lean

Jackyf0a67c048ec2
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.md
index 35dcf4f0..56ccdb37 100644
--- a/Documents/Guides/create-and-run.md
+++ b/Documents/Guides/create-and-run.md
@@ -42,10 +42,10 @@ The guest shows the VM's name as its device name, in Xcode's device list and `xc
## Templates
-A template is a complete machine kept in `<library>/.templates/<id>/`. It boots once while it is built, its setup boot, and never again once it is frozen. `vm create` without `--no-template` works out the template key from its options and the two IPSWs before anything is restored: the guest device, the iOS and cloudOS versions and builds, the patch preset and the boot-chain patches it resolves to, the bundle series (`2.8` for 2.8.x), the disk size, and the slimming switches below. Then:
+A template is a complete machine kept in `<library>/.templates/<id>/`. It boots once while it is built, its setup boot, and never again once it is frozen. `vm create` without `--no-template` works out the template key from its options and the two IPSWs before anything is restored: the guest device, the iOS and cloudOS versions and builds, the patch preset and the boot-chain patches it resolves to, the bundle series (`2.8` for 2.8.x), the disk size, what is trimmed from the guest's System volume (`--trim`), and the slimming switches below. Then:
- If a template with that key exists, the VM is cloned from it with a new identity, given the requested CPU, memory and network, and booted once to check vphoned. This takes seconds and needs neither root nor the IPSWs; nothing is downloaded.
-- Otherwise the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`, followed by the setup boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.
+- Otherwise the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`: `cfw install`, the offline trim, then the setup boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. The restore tree is removed before the freeze whatever `--keep-artifacts` says: a template never keeps it, because its ~11 GB would stay pinned for as long as the template lives and no clone can use it. `--keep-artifacts` keeps it only with `--no-template`, and `vm template adopt` removes it too. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.
```sh
vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a
@@ -55,6 +55,21 @@ vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144
`--template <id>` clones from a template by its identifier (or a unique prefix of four or more digits) and takes no IPSW options. `--device`, `--preset`, `--disk-size` and the slimming switches, when given, must match the template's; a clone cannot change them. CPU, memory, screen and network are not part of the key.
+### Offline trim
+
+After `cfw install`, a template build deletes system files the guest never needs from its System volume, offline, with the volume mounted on the host. `--trim` on `vm create` (default `standard`) and `--tier` on `vm template trim` pick the tier:
+
+| Tier | Deletes | About |
+| --- | --- | --- |
+| `none` | nothing | |
+| `conservative` | the contents of `usr/standalone/update` (software-update ramdisk, baseband firmware) | 0.35 GB |
+| `standard` | conservative, plus the AirPods/Beats pairing assets (`PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets`), the watch faces (`NanoTimeKit/FaceBundles`) and the `LinguisticData/RequiredAssets_*.bundle` of every language not kept | 1.2 GB |
+| `aggressive` | reserved: refused until it has been validated on a guest | |
+
+`--keep-languages` (default `en,zh-Hans,zh`; English is always kept) chooses the languages standard keeps. The tier, the version of the list and the kept languages are part of the template key (`standard/1/en,zh,zh-Hans`), so templates trimmed differently never match. Trimming cannot be undone: a clone cannot get the files back.
+
+The deleted files free nothing at first. The guest's original system snapshot (`orig-fs.disabled.rn-*`, left by `cfw install`) still holds every block, and the host cannot delete it, even as root. The setup boot deletes it as its first step, and only then is the space returned. So a trim is refused for a template that gets no setup boot, and a trimmed template is frozen or adopted only once its snapshot is gone. `vm template trim` needs no root, runs on a stopped machine that has not been cloned from a template, or on an unfinished `.building-…` folder, and refuses a frozen template.
+
### Setup boot and slimming
The setup boot finishes the template the way every clone should start. It boots the template once and, through vphoned, in this order:
@@ -71,7 +86,9 @@ Every step has a deadline. A failed step stops the VM, records nothing and leave
| Switch | Default | Effect |
| --- | --- | --- |
-| `--slim on\|off` | on | `off` keeps every app and service. The setup boot still runs: Setup is skipped and the snapshot deleted. |
+| `--slim on\|off` | on | `off` trims nothing and keeps every app and service. The setup boot still runs: Setup is skipped and the snapshot deleted. |
+| `--trim none\|conservative\|standard` | standard | The offline trim above. |
+| `--keep-languages <list>` | `en,zh-Hans,zh` | The languages `--trim standard` keeps. |
| `--service-profile trimmed\|none` | trimmed | vphoned's trimmed profile: about 140 launchd jobs off, the App Store daemons and sign-in follow-up among them. |
| `--remove-apps on\|off` | on | Removes App Store, Home, TV, News, FaceTime, iTunes Store, Messages, Games, Find My and Wallet. Camera and Phone stay. |
| `--keep-apps <ids>` | none | Bundle IDs from that list to keep, comma-separated (`com.apple.findmy,com.apple.Passbook`). |
@@ -83,16 +100,17 @@ What every clone inherits from the template: Setup done, the apps and services a
### Finishing a VM as a template
-Launchpad builds a machine with its own pipeline and boots it once, leaving it at Setup. To turn such a machine (or any VM straight after creating it) into a template, stop it, give it the setup boot, and adopt it:
+Launchpad builds a machine with its own pipeline and boots it once, leaving it at Setup. To turn such a machine (or any VM straight after creating it) into a template, stop it, trim it, give it the setup boot, and adopt it:
```sh
vphone-cli vm stop phone-src
+vphone-cli vm template trim phone-src --tier standard # offline, no root; frees nothing until the setup boot
vphone-cli vm template setup phone-src # headless; --window to watch, slimming switches as for vm create
vphone-cli vm template adopt phone-src # key from its records and what the setup boot recorded
vphone-cli vm create phone-d --template <id> --skip-first-boot
```
-`vm template setup` refuses a running VM and a frozen template. On a VM it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done. Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, and freezes it on success.
+`vm template setup` refuses a running VM and a frozen template. It trims nothing itself: the tier `vm template trim` recorded is kept, and a `--trim` that names another tier is refused. On a VM it reports an app vphoned would not remove and leaves it out of the recorded steps, so the adopted key says what was really done. Given a `.building-…` name from `vm template list` (a `vm create` whose setup boot failed), it sets the build up to its key, which fixes the slimming, runs the offline trim first if the build stopped before it, and freezes it on success.
### Shared secrets
@@ -101,14 +119,20 @@ Every machine cloned from one template shares, with the template and with each o
```sh
vphone-cli vm template list # id, key summary, STALE with the reasons
vphone-cli vm template show <id> --json
+vphone-cli vm template trim myphone --tier standard # trim a stopped VM before adopting it
vphone-cli vm template setup myphone # the setup boot, on a stopped VM
vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template
vphone-cli vm template delete <id>
```
- **Stale.** A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its key has an older format, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.
-- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template setup` recorded in its `Template.plist`). The VM leaves `vm list`. Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.
+- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image, Launchpad's `launchpad.json`, and the steps `vm template trim` and `vm template setup` recorded in its `Template.plist`). The VM leaves `vm list`. Adopt a VM straight after its setup boot: every clone inherits what its guest has done since. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.
- **Never booted once frozen.** `vm launch` and `vphone-vm` refuse a frozen template, in DFU too; no machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted after being frozen would write state into the blocks every later clone inherits, and the clones made before it would stop sharing them.
+- **Machines using it.** A machine cloned from a template records the template in `TemplateSource.plist`; a `vm clone` of it keeps the record (the copy shares the template's blocks too) and `vm export` leaves it out (an import shares nothing). `vm template list` and `show` list the machines using each template and its size on disk, and `vm info` shows a machine's template. When `vm delete` removes the last machine cloned from a template that still exists, it says so, and never deletes the template itself:
+
+ ```
+ note: template 3f2a91c0d4e7 (~17.40 GB) is no longer used by any machine; remove it with `vphone-cli vm template delete 3f2a91c0d4e7`
+ ```
- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.
## Manual stages
diff --git a/Research/Host/machine_templates.md b/Research/Host/machine_templates.md
index 0945dddd..4fe26932 100644
--- a/Research/Host/machine_templates.md
+++ b/Research/Host/machine_templates.md
@@ -35,7 +35,7 @@ Everything a clone inherits and could not change without a restore:
| boot-chain plan digest | the preset resolved against the two versions | `PatchPlan.plist` `EnabledPatches`, `Parameters` |
| bundle series | this `vphone-cli`'s `Info.plist` | `launchpad.json` `bootChain`, else the `Guest` receipt part when `cfw install` wrote it, else this `vphone-cli` |
| disk size (decimal GB) | `--disk-size` | `Disk.img` length |
-| slimming: trim tier, setup boot, service profile, service groups, removed apps | the slimming switches (below) | `Template.plist` steps `vm template setup` recorded, else nothing done |
+| slimming: trim, setup boot, service profile, service groups, removed apps | the slimming switches (below); the trim as `VPhoneSystemTrimSpec.keyValue` (`standard/1/en,zh,zh-Hans`) | `Template.plist` steps `vm template trim` and `vm template setup` recorded, else nothing done |
| format version | 2 | 2 |
The identifier is the first 12 hex digits of the SHA-256 of one
@@ -77,12 +77,25 @@ re-resolves with the template's own `PatchSelection.plist`.
`BootChainBundleVersion`, `SourceMachine` (the name a derived mDNS name
follows from), `Frozen`, `FrozenAt`, `Steps` (`SnapshotDeleted`,
`SetupDone`, `ServiceProfile`, `ServiceGroups`, `RemovedApps`, `TrimTier`).
+- `TemplateSource.plist` in a machine cloned from a template: `Identifier`,
+ `Cloned`. A plain `vm clone` keeps it (the copy shares the template's
+ blocks too); `vm export` excludes it (an import shares nothing).
+ `VPhoneMachineTemplates.usage` maps each template to the machines (and
+ templates adopted from such machines) that carry its identifier. `vm
+ template list/show` print it with the template's allocated size; `vm delete`
+ of the last machine using a template that still exists prints a note to
+ delete it (`unusedTemplate(after:in:)`), never deleting it itself.
- A build happens in `.building-<id>-<uuid>/<id>/` and is frozen by writing
`Frozen = true` and one `renamex_np(RENAME_EXCL)` to `.templates/<id>`. A
listed template is always complete; a race with another build of the same
key fails the rename and leaves the build unfrozen.
- `freeze` and `adopt` refuse unless `Steps` produced the slimming the key
- promises.
+ promises, and refuse a trim whose `SnapshotDeleted` is false
+ (`VPhoneMachineTemplateSteps.problems`).
+- `freeze` and `adopt` remove the restore tree (`iPhone*_Restore`): a template
+ never keeps it. `vm create` removes it before the trim whatever
+ `--keep-artifacts` says and warns that the flag keeps it only with
+ `--no-template`; `adopt` says it removed it.
- A clone drops `Template.plist`, `Snapshots/` and `vphone.sock`.
## Never booting once frozen
@@ -114,12 +127,14 @@ and `vm template setup` to the key's slimming:
| Switches | trim | setup boot | services | groups | removed apps |
| --- | --- | --- | --- | --- | --- |
-| none (`--slim on`) | `defaultTrimTier` (`none` until offline trim lands) | yes | trimmed | none | list C (10 apps) |
+| none (`--slim on`) | `defaultTrim`: `standard/1/en,zh,zh-Hans` | yes | trimmed | none | list C (10 apps) |
| `--slim off` | none | yes | none | none | none |
| `--service-profile none` | default | yes | none | none | list C |
| `--remove-apps off` | default | yes | trimmed | none | none |
| `--keep-apps a,b` | default | yes | trimmed | none | list C minus a, b |
| `--accounts-off` | default | yes | trimmed | `accounts` | list C |
+| `--trim conservative` | `conservative/1` | yes | trimmed | none | list C |
+| `--keep-languages ja` | `standard/1/en,ja` | yes | trimmed | none | list C |
List C: `com.apple.AppStore`, `Home`, `tv`, `news`, `facetime`, `MobileStore`,
`MobileSMS`, `games`, `findmy`, `Passbook` (P0 and P1 verified each stays
@@ -127,7 +142,10 @@ removed across a respring and a reboot on 27.0). Camera stays for camera
passthrough checks; Phone lives on the System volume and vphoned refuses it.
Contradictions are refused, all at once: `--slim off` with any slimming
switch, `--accounts-off` without the trimmed profile, `--keep-apps` naming an
-app outside list C or with `--remove-apps off`, an unknown tier or profile.
+app outside list C or with `--remove-apps off`, an unknown or reserved tier
+(`aggressive`), `--keep-languages` with a tier that removes no language data,
+an unknown profile. `--keep-languages` alone means `--trim standard` keeping
+those languages.
`--no-template` takes no slimming switch; `--template <id>` takes them only to
check them against the template.
@@ -145,6 +163,110 @@ switch the profile on a running machine: a clone of a trimmed template starts
trimmed without a reboot of its own, and `services.profile.apply none` undoes
it on that clone.
+## Offline trim
+
+Code: `VPhoneKit/VPhoneCoreKit/Bundle/VPhoneSystemTrim.swift` (tiers, the
+versioned list, path rules, applying a trim to a volume root by descriptor,
+reading the disk layout) and
+`VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateTrimmer.swift`
+(attach, mount, trim, unmount, detach, record). Tests:
+`VPhoneKit/VPhoneCoreKitTests/Bundle/SystemTrimTests.swift`.
+
+List version 1, paths relative to the System volume:
+
+| Tier | Entry | Selection |
+| --- | --- | --- |
+| conservative | `usr/standalone/update` | its contents (243 MB SU ramdisk, 114 MB baseband firmware) |
+| standard | `System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets` | the folder |
+| standard | `System/Library/NanoTimeKit/FaceBundles` | its contents |
+| standard | `System/Library/LinguisticData` | children `RequiredAssets_<lang>.bundle` whose `<lang>` is not kept |
+| aggressive | reserved (other languages' `.lproj`, Health, some fonts) | refused: not validated |
+
+These are the deletions measured and booted on 2026-10-07/08 (see
+`Research/Guest/template_snapshot_deletion.md`). Never listed: the dyld
+shared cache and its `.symbols` (the CFW cache patcher resolves symbols from
+it), ML models, `/Applications`. Changing an entry raises
+`VPhoneSystemTrim.listVersion`.
+
+The key value is `<tier>/<list version>[/<kept languages>]`, `none` without
+trim. The kept languages default to `en,zh-Hans,zh` (`zh` is the bundle
+`zh-Hans` shares); English is always kept. A machine already trimmed takes
+only the same trim again, or a heavier tier after `conservative`
+(`VPhoneSystemTrimSpec.canFollow`).
+
+How it runs, without root:
+
+1. Refuse a running machine (`VPhoneBundleActivity.requireStopped`), a frozen
+ template or a folder directly in `.templates`, and a machine with a
+ `TemplateSource.plist` (its blocks are the template's; deleting files would
+ free nothing).
+2. `hdiutil attach -nomount -imagekey diskimage-class=CRawDiskImage Disk.img`
+ (`Disk.img` must be a regular single-link file, owned by the invoking user
+ under sudo).
+3. The `Apple_APFS` partition from the attach output, its
+ `APFSContainerReference` from `diskutil info -plist`, and the one volume
+ whose `Roles` contain `System` from `diskutil apfs list -plist`, after
+ checking the container's physical store is that partition. No slice
+ numbers.
+4. `diskutil mount -mountOptions nosuid,nodev,noowners,nobrowse -mountPoint
+ <mkdtemp 0700 folder in /private/var/tmp>/system <volume>`. A user who
+ attached the image may mount it this way; as root it works the same.
+5. Pin the mount point by descriptor, check `f_mntfromname` is the volume,
+ and refuse unless `System/Library/CoreServices/SystemVersion.plist` exists.
+6. Delete each entry through `VPhoneConfinedDirectory`: every component is
+ opened `O_NOFOLLOW`, a link on the way or a volume change is refused, a
+ link at the leaf is deleted as a link, and each target must pass
+ `VPhoneSystemTrimSpec.permits` first. Bytes removed are the `st_blocks` of
+ what went, a second hard link counting as nothing; each entry is logged.
+7. Unmount (`force` as a fallback) and detach (`-force` as a fallback) on
+ every way out, then record `Steps.TrimTier`.
+
+### The snapshot dependency
+
+The trimmed blocks stay allocated until the guest deletes the
+`orig-fs.disabled.rn-*` snapshot `cfw install` left; the host cannot (SIP,
+`-69863` even as root). Only the setup boot does it
+(`apfs.snapshot.delete`). Two rules follow:
+
+- `VPhoneMachineTemplateSlimming.problems`: a key with a trim but no setup
+ boot is refused before anything is built. Every key `vm create` resolves
+ has the setup boot (`--slim off` included), so this guards keys built by
+ hand; `--trim` defaults to `standard`.
+- `VPhoneMachineTemplateSteps.problems`: `freeze` and `adopt` refuse a trim
+ whose `SnapshotDeleted` is false. Refused rather than warned about: such a
+ template costs exactly what an untrimmed one does while its clones have
+ lost the files, and its key would promise savings it never made.
+
+### Measured
+
+2026-10-08, iPhone17,3 iOS 27.0 (24A435) / cloudOS 26.4, created by
+Launchpad (bundle 2.7.0 local, standard preset) and stopped after its first
+boot; `vm template trim p3-src --tier standard` from a build-directory
+`vphone-cli`, as the user, no root:
+
+| Entry | Removed | Bytes |
+| --- | --- | --- |
+| `usr/standalone/update` | 16 items | 361.7 MB |
+| `…/com_apple_MobileAsset_SharingDeviceAssets` | the folder | 237.6 MB |
+| `NanoTimeKit/FaceBundles` | 76 bundles | 147.9 MB |
+| `LinguisticData` | 57 `RequiredAssets_*` bundles (en, zh-Hans, zh kept) | 418.7 MB |
+| total | | 1.17 GB |
+
+The run took 4.7 s. `Disk.img` went from 35,977,296 to 35,977,880 blocks:
+the snapshot keeps everything, as expected. A second run removed nothing; a
+conservative trim afterwards and `aggressive` were refused, and so was
+`vm template adopt --force` (trim without snapshot deletion). The machine then
+booted through Launchpad to the Setup greeting with vphoned answering and 258
+apps registered, no panic. With P4's snapshot deletion the 2026-10-07
+prototype returned 1.19 GB for the same deletions
+(`Research/Guest/template_snapshot_deletion.md`).
+
+`vm delete` of the second of two machines cloned from a template printed
+`note: template 2246f982776c (~18.92 GB) is no longer used by any machine; …`;
+the first printed nothing, and `vm template list` showed `machines using it:
+p3-a, p3-b`, then `none`. The size is the template's allocated bytes,
+blocks it shares with other files included.
+
## Setup boot
`VPhoneTemplateSetupBoot.run()` drives a `VPhoneTemplateSetupMachine`. The
@@ -187,7 +309,8 @@ On any failure the VM is killed, the failure names the step
(`VPhoneTemplateSetupFailure`), and nothing is recorded:
`recordSetupBoot` writes only a complete outcome (`SnapshotDeleted`,
`SetupDone`, `ServiceProfile`, `ServiceGroups`, `RemovedApps`; `TrimTier` is
-left to the trim), so `freeze` keeps refusing the build.
+left to the trim, and the snapshot is gone before the trim's record is ever
+checked), so `freeze` keeps refusing the build.
The device name: `vphone-vm` pins the guest's name to the machine's name
(`device.name.set`) on every connect, and the pin lives in
@@ -212,19 +335,24 @@ made after the latest one, as these clones were.
## Lifecycle
- **vm create** (default): key from the options and switches → lock →
- restore and `cfw install` into the staging folder (offline file trimming
- belongs inside `cfw install` and records `Steps.TrimTier`) → setup boot →
- recorded key must equal the requested one → `freeze` → clone.
- A setup boot failure leaves the build; `vm template setup .building-…`
- retries it under the lock and freezes it on success.
+ restore and `cfw install` into the staging folder → restore tree removed →
+ offline trim (records `Steps.TrimTier`) → setup boot (step 0 deletes the
+ snapshot; records `SnapshotDeleted`, `SetupDone`, the profile, groups and
+ apps) → recorded key must equal the requested one → `freeze` → clone.
+ A failure leaves the build; `vm template setup .building-…` runs the trim
+ if the build stopped before it recorded one, retries the setup boot under
+ the lock and freezes the build on success.
- **Launchpad** (P5) builds a machine with its step-by-step pipeline, whose
first boot leaves it running at Setup; it stops it, runs
- `vm template setup <name> [switches]`, then `vm template adopt <name>`,
- then `vm create <name> --template <id> --skip-first-boot` and its own first
- boot. `vm template setup` on a machine writes an unfrozen `Template.plist`
- (key from its records) when it has none, and records the steps there.
+ `vm template trim <name> --tier …`, `vm template setup <name> [switches]`,
+ `vm template adopt <name>`, then `vm create <name> --template <id>
+ --skip-first-boot` and its own first boot. `vm template trim` and
+ `vm template setup` on a library machine write an unfrozen `Template.plist`
+ (key from its records) when it has none, and record their steps there.
+ The setup boot trims nothing: it keeps the tier `vm template trim`
+ recorded, and refuses a `--trim` that names another one.
- `freeze` and `adopt` refuse a record whose steps did not produce the key's
- slimming.
+ slimming, and a trim whose snapshot was not deleted.
## Staleness
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateTrimmer.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateTrimmer.swift
new file mode 100644
index 00000000..1691140d
--- /dev/null
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateTrimmer.swift
@@ -0,0 +1,184 @@
+import ArgumentParser
+import Darwin
+import Foundation
+import VPhoneCoreKit
+
+/// Offline trim of a stopped machine's guest System volume: attach its
+/// `Disk.img` without mounting, find the System-role volume, mount it
+/// read-write inside a private folder, delete the trim's entries
+/// (``VPhoneSystemTrimSpec/apply(to:log:)``), unmount and detach, then record
+/// the trim in the machine's `Template.plist` steps.
+///
+/// Root is not needed: an image attached by a user mounts for that user
+/// with `noowners`. A template build under sudo runs it as root all the
+/// same. Either way the volume is mounted `nosuid,nodev,nobrowse` in a 0700
+/// folder made by `mkdtemp`, and every deletion is descriptor relative and
+/// refuses links, so nothing on the guest volume can point it at a host path.
+///
+/// What it deletes stays allocated until the guest deletes its `orig-fs`
+/// snapshot during the setup boot; a template is frozen only after that.
+enum VPhoneMachineTemplateTrimmer {
+ /// Trims the machine at `bundle` and records the trim.
+ ///
+ /// - Parameters:
+ /// - label: The name messages use: the machine's, or the staging folder's.
+ /// - newRecord: The unfrozen `Template.plist` to write when the machine
+ /// has none (a library machine Launchpad is building into a template).
+ @discardableResult
+ static func trim(
+ _ bundle: VPhoneBundle,
+ label: String,
+ spec: VPhoneSystemTrimSpec,
+ newRecord: VPhoneMachineTemplateRecord?,
+ log: (String) -> Void = { print($0) },
+ ) throws -> VPhoneSystemTrimResult {
+ try requireTrimmable(bundle, label: label, spec: spec)
+ if spec.tier == .none {
+ log("[*] Trim none: nothing to delete")
+ try record(spec, in: bundle, newRecord: newRecord)
+ return VPhoneSystemTrimResult(trim: spec.keyValue, entries: [])
+ }
+ let disk = try diskImage(of: bundle)
+ let before = allocatedBytes(disk)
+ log("[*] Trimming \(label) to \(spec.keyValue): \(disk.path)")
+ let result = try withMountedSystemVolume(disk) { root in
+ try spec.apply(to: root) { log(" [trim] \($0)") }
+ }
+ let after = allocatedBytes(disk)
+ log("[+] Trim \(spec.keyValue) removed \(VPhoneSystemTrim.formatBytes(result.bytes)) from the System volume")
+ log(" Disk.img allocated \(VPhoneSystemTrim.formatBytes(before)) → \(VPhoneSystemTrim.formatBytes(after)); "
+ + "the guest's orig-fs snapshot keeps the trimmed blocks until the setup boot deletes it")
+ try record(spec, in: bundle, newRecord: newRecord)
+ return result
+ }
+
+ // MARK: Checks
+
+ /// Stopped, not a frozen template, not a clone of one, and not already
+ /// trimmed in a way this trim cannot follow
+ /// (``VPhoneSystemTrimSpec/canFollow(recorded:)``).
+ static func requireTrimmable(_ bundle: VPhoneBundle, label: String, spec: VPhoneSystemTrimSpec) throws {
+ guard spec.tier.isSupported else {
+ throw VPhoneSystemTrimError.unsupportedTier(spec.tier.rawValue)
+ }
+ let url = bundle.url.absoluteURL.standardizedFileURL
+ let record = try VPhoneMachineTemplates.readRecord(inBundle: url)
+ if url.deletingLastPathComponent().lastPathComponent == VPhoneMachineTemplates.directoryName || record?.frozen == true {
+ throw VPhoneMachineTemplateError.frozen(identifier: record?.identifier ?? url.lastPathComponent)
+ }
+ if let source = VPhoneMachineTemplates.readSource(inBundle: url) {
+ throw VPhoneSystemTrimError.clonedFromTemplate(machine: label, template: source.identifier)
+ }
+ try VPhoneBundleActivity.requireStopped(bundle)
+ if let recorded = record?.steps.trimTier, !spec.canFollow(recorded: recorded) {
+ throw VPhoneSystemTrimError.downgrade(machine: label, recorded: recorded, requested: spec.keyValue)
+ }
+ }
+
+ private static func record(_ spec: VPhoneSystemTrimSpec, in bundle: VPhoneBundle, newRecord: VPhoneMachineTemplateRecord?) throws {
+ try VPhoneMachineTemplates.recordSteps(inBundle: bundle.url, creating: newRecord.map { record in { record } }) {
+ $0.trimTier = spec.keyValue
+ }
+ }
+
+ /// `Disk.img`: a regular file with one link, owned by the account that
+ /// started a sudo run when there is one.
+ private static func diskImage(of bundle: VPhoneBundle) throws -> URL {
+ let disk = bundle.url.appendingPathComponent(bundle.manifest.diskImage)
+ var info = stat()
+ guard lstat(disk.path, &info) == 0, info.st_mode & S_IFMT == S_IFREG, info.st_nlink == 1 else {
+ throw ValidationError("\(disk.path) is not a plain disk image file.")
+ }
+ if geteuid() == 0, let user = VPhoneInvokingUser.current, info.st_uid != user.uid {
+ throw ValidationError("\(disk.path) is not owned by the account that started this command.")
+ }
+ return disk
+ }
+
+ private static func allocatedBytes(_ url: URL) -> UInt64 {
+ var info = stat()
+ guard stat(url.path, &info) == 0 else { return 0 }
+ return UInt64(max(info.st_blocks, 0)) * 512
+ }
+
+ // MARK: Mounting
+
+ /// Attaches `disk`, mounts its System-role volume and hands `body` its
+ /// root; unmounts and detaches on every way out.
+ private static func withMountedSystemVolume<T>(_ disk: URL, _ body: (VPhoneConfinedDirectory) throws -> T) throws -> T {
+ let work = try makeWorkDirectory()
+ defer { rmdir(work.appendingPathComponent("system").path); rmdir(work.path) }
+ let mountPoint = work.appendingPathComponent("system")
+ guard mkdir(mountPoint.path, 0o700) == 0 else {
+ throw ValidationError("Cannot create \(mountPoint.path): \(String(cString: strerror(errno)))")
+ }
+
+ let attached = try tool(
+ "/usr/bin/hdiutil",
+ ["attach", "-nomount", "-imagekey", "diskimage-class=CRawDiskImage", disk.path],
+ )
+ let disks = VPhoneGuestDiskLayout.attachedDisks(fromAttachOutput: attached)
+ guard let whole = disks.wholeDisk, VPhoneGuestDiskLayout.isDeviceName(whole) else {
+ if let range = attached.range(of: #"/dev/disk[0-9]+"#, options: .regularExpression) {
+ _ = try? tool("/usr/bin/hdiutil", ["detach", "-force", String(attached[range])])
+ }
+ throw VPhoneSystemTrimError.layout("hdiutil attached no disk image")
+ }
+ defer {
+ if (try? tool("/usr/bin/hdiutil", ["detach", whole])) == nil {
+ _ = try? tool("/usr/bin/hdiutil", ["detach", "-force", whole])
+ }
+ }
+ guard let store = disks.store, VPhoneGuestDiskLayout.isDeviceName(store) else {
+ throw VPhoneSystemTrimError.layout("the image on \(whole) has no APFS partition")
+ }
+ let info = try tool("/usr/sbin/diskutil", ["info", "-plist", store])
+ guard
+ let plist = try? PropertyListSerialization.propertyList(from: Data(info.utf8), format: nil) as? [String: Any],
+ let container = plist["APFSContainerReference"] as? String,
+ VPhoneGuestDiskLayout.isDeviceName(container)
+ else {
+ throw VPhoneSystemTrimError.layout("\(store) is not an APFS physical store")
+ }
+ let list = try tool("/usr/sbin/diskutil", ["apfs", "list", "-plist", container])
+ let system = try VPhoneGuestDiskLayout.systemVolume(fromAPFSList: Data(list.utf8), container: container, physicalStore: store)
+
+ _ = try tool("/usr/sbin/diskutil", [
+ "mount", "-mountOptions", "nosuid,nodev,noowners,nobrowse", "-mountPoint", mountPoint.path, system,
+ ])
+ defer {
+ if (try? tool("/usr/sbin/diskutil", ["unmount", mountPoint.path])) == nil {
+ _ = try? tool("/usr/sbin/diskutil", ["unmount", "force", mountPoint.path])
+ }
+ }
+ // Every descriptor on the volume lives in this scope, so none holds
+ // it busy when the deferred unmount runs.
+ do {
+ let root = try VPhoneConfinedDirectory.pin(absolutePath: work.path).mountedVolume("system")
+ guard try root.mountedFrom() == "/dev/\(system)" else {
+ throw VPhoneSystemTrimError.layout("\(mountPoint.path) is not /dev/\(system)")
+ }
+ return try body(root)
+ }
+ }
+
+ /// A fresh 0700 folder under `/private/var/tmp`, named by `mkdtemp` so it
+ /// cannot be predicted or claimed beforehand.
+ private static func makeWorkDirectory() throws -> URL {
+ var template = Array("/private/var/tmp/vphone-trim.XXXXXXXX".utf8CString)
+ guard let made = mkdtemp(&template) else {
+ throw ValidationError("Cannot create a work folder in /private/var/tmp: \(String(cString: strerror(errno)))")
+ }
+ return URL(fileURLWithPath: String(cString: made), isDirectory: true)
+ }
+
+ @discardableResult
+ private static func tool(_ path: String, _ arguments: [String]) throws -> String {
+ let result = try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: path), arguments)
+ guard result.succeeded else {
+ let detail = result.stderr.trimmingCharacters(in: .whitespacesAndNewlines)
+ throw ValidationError("\(URL(fileURLWithPath: path).lastPathComponent) \(arguments.first ?? "") failed (\(result.exitCode)): \(detail)")
+ }
+ return result.stdout
+ }
+}
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift
index 69f652aa..898533aa 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneTemplateSetup.swift
@@ -11,6 +11,13 @@ struct VPhoneTemplateSlimmingOptions: ParsableArguments {
valueName: "on|off",
))
var slim: String?
+ @Option(help: ArgumentHelp(
+ "System files the template deletes offline: standard (default) | conservative | none. Part of the template key; vm template trim describes the tiers",
+ valueName: "tier",
+ ))
+ var trim: String?
+ @Option(help: ArgumentHelp("Languages whose linguistic data --trim standard keeps (en is always kept)", valueName: "en,zh-Hans,zh"))
+ var keepLanguages: String?
@Option(help: ArgumentHelp("Service profile the template applies: trimmed (default) | none", valueName: "profile"))
var serviceProfile: String?
@Option(help: ArgumentHelp("Remove the default system apps (App Store, TV, News, …): on (default) | off", valueName: "on|off"))
@@ -27,6 +34,8 @@ struct VPhoneTemplateSlimmingOptions: ParsableArguments {
get throws {
try VPhoneTemplateSlimmingRequest(
slim: slim.map { try VPhoneVirtualMachineConfigCommand.parseSwitch($0, option: "--slim") },
+ trimTier: trim,
+ keepLanguages: keepLanguages,
serviceProfile: serviceProfile,
removeApps: removeApps.map { try VPhoneVirtualMachineConfigCommand.parseSwitch($0, option: "--remove-apps") },
keepApps: keepApps,
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift
index d4c49378..e25678a5 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift
@@ -169,6 +169,9 @@ struct VPhoneVirtualMachineInfoCommand: ParsableCommand {
if let udid = report.udid {
print("udid: \(udid)")
}
+ if let template = report.template {
+ print("template: \(template)")
+ }
if let info = report.restoreInfo {
print("iOS: \(info.ios.version) (\(info.ios.build))")
print("cloudOS: \(info.cloudOS.version) (\(info.cloudOS.build))")
@@ -433,7 +436,15 @@ struct VPhoneVirtualMachineDeleteCommand: ParsableCommand {
return
}
}
+ let source = try VPhoneMachineTemplates.readSource(inBundle: lib.library.bundle(named: name).url)
try VPhoneBundleOperations.delete(bundleNamed: name, in: lib.library)
print("deleted \(name)")
+ // Never deleted here: another create may want it, and rebuilding it
+ // takes a restore.
+ if let template = VPhoneMachineTemplates.unusedTemplate(after: source, in: lib.library) {
+ let size = VPhoneSystemTrim.formatBytes(VPhoneMachineTemplates.allocatedBytes(of: template.url))
+ print("note: template \(template.identifier) (~\(size)) is no longer used by any machine; "
+ + "remove it with `vphone-cli vm template delete \(template.identifier)`")
+ }
}
}
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
index 848042c7..a7f98c0c 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
@@ -21,14 +21,18 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {
--no-template builds the VM on its own, with keys of its own, as before. \
--template <id> clones from a template listed by vm template list.
- A new template boots once before it is frozen (its setup boot): the orig-fs snapshot \
- is deleted, Setup Assistant skipped, first-boot work waited for, the default system apps \
+ After cfw install a new template's System volume is trimmed offline (--trim, standard \
+ by default; vm template trim describes the tiers). It then boots once before it is \
+ frozen (its setup boot): the orig-fs snapshot is deleted, which frees what the trim \
+ removed, Setup Assistant skipped, first-boot work waited for, the default system apps \
removed (App Store, Home, TV, News, FaceTime, iTunes Store, Messages, Games, Find My, \
Wallet; never Phone or Camera) and the trimmed service profile applied, then it reboots, \
is checked and shut down. Every clone starts at the Lock Screen with that state. \
- --slim off keeps every app and service (Setup is still skipped); --service-profile, \
- --remove-apps, --keep-apps and --accounts-off pick parts. Each choice is part of the key, \
- so templates with different slimming live side by side.
+ --slim off trims nothing and keeps every app and service (Setup is still skipped); \
+ --trim, --keep-languages, --service-profile, --remove-apps, --keep-apps and \
+ --accounts-off pick parts. Each choice is part of the key, so templates with different \
+ slimming live side by side. A template never keeps the restore tree: --keep-artifacts \
+ keeps it only with --no-template.
--cpu, --memory, --network and --unlock-at-startup are set on the new VM, whichever way \
it is made.
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
index eeef0502..bbd4610d 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift
@@ -133,6 +133,12 @@ public struct VPhoneVirtualMachineCreator {
}
try cloneFromTemplate(template, options: options, outputs: outputs)
case .automatic:
+ if options.keepArtifacts {
+ // A template never keeps it: ~11 GB pinned for the template's
+ // whole life, which no clone can use.
+ print("warning: --keep-artifacts keeps the restore tree only with --no-template; "
+ + "a template build always removes it")
+ }
let template = try templateForCreate(options, outputs: outputs)
try cloneFromTemplate(template, options: options, outputs: outputs)
}
@@ -164,7 +170,7 @@ public struct VPhoneVirtualMachineCreator {
outputs.add(bundle.url)
print("created \(bundle.url.path)")
- try buildGuest(at: bundle.url, options: options, outputs: outputs)
+ try buildGuest(at: bundle.url, options: options, keepsRestoreTree: options.keepArtifacts, outputs: outputs)
try applySettings(options)
if !options.skipsFirstBoot {
print("\n=== First boot check ===")
@@ -174,8 +180,13 @@ public struct VPhoneVirtualMachineCreator {
/// `fw prepare`, `fw patch`, the restore and `cfw install` into the machine
/// folder at `bundleURL`, which `vm new` made. Removes the restore tree
- /// afterwards unless `--keep-artifacts`. Starts the guest only in DFU.
- private func buildGuest(at bundleURL: URL, options: Options, outputs: VPhoneCreatedOutputs) throws {
+ /// afterwards unless `keepsRestoreTree`. Starts the guest only in DFU.
+ private func buildGuest(
+ at bundleURL: URL,
+ options: Options,
+ keepsRestoreTree: Bool,
+ outputs: VPhoneCreatedOutputs,
+ ) throws {
let v = options.verbosity
print("\n=== fw prepare ===")
try runFWPrepare(options: options, bundleURL: bundleURL)
@@ -201,7 +212,7 @@ public struct VPhoneVirtualMachineCreator {
// CFW install is the last consumer of the built restore tree (it copies
// the SystemOS/AppOS cryptexes from it onto Disk.img); reclaim it now.
- if !options.keepArtifacts, let bundle = try? VPhoneBundle.load(at: bundleURL),
+ if !keepsRestoreTree, let bundle = try? VPhoneBundle.load(at: bundleURL),
let removed = try? VPhoneRestoreInfo.removeBuiltFirmware(fromBundle: bundle)
{
print("[+] Removed built firmware \(removed)/ to save space (--keep-artifacts to keep)")
@@ -234,6 +245,10 @@ public struct VPhoneVirtualMachineCreator {
throw ValidationError("Specify both iPhone and cloudOS IPSW sources when running without a terminal.")
}
print("\n=== Template ===")
+ let slimming = Self.templateSlimming(options)
+ guard slimming.problems.isEmpty else {
+ throw ValidationError("Cannot build this template: \(slimming.problems.joined(separator: "; ")). Pass --trim none.")
+ }
let sources = try VPhoneFirmwarePreparer.resolveSources(
iPhoneSource: phoneSource,
cloudOSSource: cloudSource,
@@ -246,7 +261,7 @@ public struct VPhoneVirtualMachineCreator {
cloudOS: .init(version: sources.cloud.version, build: sources.cloud.build),
preset: options.patchPreset,
diskSizeGB: options.diskSizeGB,
- slimming: options.slimming,
+ slimming: slimming,
)
print("[*] Template key \(key.identifier): \(key.summary)")
@@ -269,6 +284,15 @@ public struct VPhoneVirtualMachineCreator {
return try buildTemplate(key, options: options, outputs: outputs)
}
+ /// What a template built for these options is slimmed by, part of its
+ /// key: the switches `VPhoneTemplateSlimmingRequest` resolved. `--slim off`
+ /// resolves to trim none. A trim without the setup boot is refused before
+ /// the build (`slimming.problems`): nothing else deletes the guest's
+ /// orig-fs snapshot, and without that a trim frees nothing.
+ static func templateSlimming(_ options: Options) -> VPhoneMachineTemplateSlimming {
+ options.slimming
+ }
+
private func requireCurrent(_ template: VPhoneMachineTemplate) throws -> VPhoneMachineTemplate {
let reasons = VPhoneMachineTemplateKeys.staleReasons(template)
guard reasons.isEmpty else {
@@ -316,13 +340,32 @@ public struct VPhoneVirtualMachineCreator {
inBundle: bundle.url,
)
- try buildGuest(at: bundle.url, options: options, outputs: outputs)
+ try buildGuest(at: bundle.url, options: options, keepsRestoreTree: false, outputs: outputs)
+ // A template never keeps the restore tree, whatever
+ // --keep-artifacts says; freeze removes it too, this says so.
+ if let tree = try VPhoneMachineTemplates.removeRestoreTree(of: VPhoneBundle.load(at: bundle.url)) {
+ print("[+] Removed built firmware \(tree)/ (a template never keeps it)")
+ }
- // Offline file trimming runs inside the CFW install above and
- // records Steps.TrimTier there (key.slimming.trimTier says which
- // tier). The snapshot it cannot delete from the host goes in the
- // setup boot's first step, which frees what the trim removed.
+ // Offline trim of the System volume, after cfw install. Each
+ // stage records its work with VPhoneMachineTemplates.recordSteps
+ // before the freeze; freeze refuses steps that do not match the
+ // key, and a trim whose orig-fs snapshot was not deleted.
+ let trim = try VPhoneSystemTrimSpec(keyValue: key.slimming.trimTier)
+ if trim.tier != .none {
+ print("\n=== Offline trim ===")
+ try VPhoneMachineTemplateTrimmer.trim(
+ VPhoneBundle.load(at: bundle.url),
+ label: key.identifier,
+ spec: trim,
+ newRecord: nil,
+ )
+ }
+ // The setup boot deletes the orig-fs snapshot first, which frees
+ // what the trim removed, then records snapshotDeleted, setupDone,
+ // the service profile and the removed apps. It leaves trimTier
+ // as the trim recorded it.
if key.slimming.setupBoot {
print("\n=== Template setup boot ===")
// With a window, as the first-boot check: this is the guest's
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
index ec6b1f95..d47570ab 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift
@@ -30,6 +30,7 @@ struct VPhoneVirtualMachineTemplateCommand: ParsableCommand {
VPhoneVirtualMachineTemplateShowCommand.self,
VPhoneVirtualMachineTemplateSetupCommand.self,
VPhoneVirtualMachineTemplateAdoptCommand.self,
+ VPhoneVirtualMachineTemplateTrimCommand.self,
VPhoneVirtualMachineTemplateDeleteCommand.self,
],
)
@@ -48,10 +49,15 @@ struct VPhoneMachineTemplateReport: Encodable {
var sourceMachine: String?
var steps: VPhoneMachineTemplateSteps
var diskSizeBytes: Int64
+ /// What the template's files take on disk (`st_blocks`): what deleting
+ /// it frees once no machine shares its blocks.
+ var allocatedBytes: UInt64
+ /// Machines cloned from it (their `TemplateSource.plist`), sorted.
+ var machines: [String]
var stale: Bool
var staleReasons: [String]
- init(_ template: VPhoneMachineTemplate) {
+ init(_ template: VPhoneMachineTemplate, usage: [String: [String]]) {
let record = template.record
id = record.identifier
path = template.url.path
@@ -62,6 +68,8 @@ struct VPhoneMachineTemplateReport: Encodable {
sourceMachine = record.sourceMachine
steps = record.steps
diskSizeBytes = (try? template.bundle().diskSizeBytes) ?? 0
+ allocatedBytes = VPhoneMachineTemplates.allocatedBytes(of: template.url)
+ machines = usage[template.identifier] ?? []
staleReasons = VPhoneMachineTemplateKeys.staleReasons(template)
stale = !staleReasons.isEmpty
}
@@ -97,7 +105,8 @@ struct VPhoneVirtualMachineTemplateListCommand: ParsableCommand {
func run() throws {
let listing = try VPhoneMachineTemplates.list(in: lib.library)
- let reports = listing.templates.map(VPhoneMachineTemplateReport.init)
+ let usage = VPhoneMachineTemplates.usage(in: lib.library)
+ let reports = listing.templates.map { VPhoneMachineTemplateReport($0, usage: usage) }
if json {
try print(encodeJSON(VPhoneMachineTemplateListReport(
templates: reports,
@@ -115,6 +124,8 @@ struct VPhoneVirtualMachineTemplateListCommand: ParsableCommand {
for report in reports {
let state = report.stale ? " STALE" : ""
print("\(report.id) \(report.key.summary)\(state)")
+ print(" \(VPhoneSystemTrim.formatBytes(report.allocatedBytes)) on disk; "
+ + "machines using it: \(report.machines.isEmpty ? "none" : report.machines.joined(separator: ", "))")
for reason in report.staleReasons {
print(" stale: \(reason)")
}
@@ -138,7 +149,10 @@ struct VPhoneVirtualMachineTemplateShowCommand: ParsableCommand {
@Flag(name: .shortAndLong, help: "Emit JSON") var json = false
func run() throws {
- let report = try VPhoneMachineTemplateReport(VPhoneMachineTemplates.template(id, in: lib.library))
+ let report = try VPhoneMachineTemplateReport(
+ VPhoneMachineTemplates.template(id, in: lib.library),
+ usage: VPhoneMachineTemplates.usage(in: lib.library),
+ )
if json {
try print(encodeJSON(report))
return
@@ -152,7 +166,8 @@ struct VPhoneVirtualMachineTemplateShowCommand: ParsableCommand {
print("preset: \(key.patchPreset) boot chain \(key.bootChainPlanDigest.prefix(12))")
print("bundle: series \(key.bundleSeries), boot chain \(report.bootChainBundleVersion ?? "unknown"), "
+ "built with \(report.builtWithBundleVersion ?? "unknown")")
- print("disk: \(key.diskSizeGB) GB")
+ print("disk: \(key.diskSizeGB) GB, \(VPhoneSystemTrim.formatBytes(report.allocatedBytes)) on disk")
+ print("machines: \(report.machines.isEmpty ? "none" : report.machines.joined(separator: ", "))")
print("slimming: \(key.slimming.summary)")
if !key.slimming.removedApps.isEmpty {
print("removed: \(key.slimming.removedApps.joined(separator: ","))")
@@ -185,15 +200,17 @@ struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
records nothing.
A VM: stop it first (a machine Launchpad created sits at Setup after its first boot; that \
- is fine). Then vm template adopt <name> freezes it with what this recorded. An app that \
- will not go is reported and left out of the template's key.
+ is fine), and trim it with vm template trim beforehand: the snapshot deletion here is what \
+ frees the trimmed files, and this boot trims nothing. --trim, when given, must match the \
+ tier vm template trim recorded. Then vm template adopt <name> freezes it with what this \
+ recorded. An app that will not go is reported and left out of the template's key.
A .building-… name from vm template list: a vm create whose template build failed. Its \
key fixes the slimming, so switches that disagree are refused, every app must go, and on \
success the template is frozen and vm create uses it.
Slimming: --slim off skips the app removal and the service profile; the setup boot still \
- skips Setup and deletes the snapshot.
+ skips Setup and deletes the snapshot, so a trim recorded before it is kept.
""",
)
@@ -220,10 +237,23 @@ struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
let bundle = try library.bundle(named: target)
try VPhoneMachineTemplates.requireBootable(bundleURL: bundle.url)
try VPhoneBundleActivity.requireStopped(bundle)
- let wanted = try slimming.resolve()
- if wanted.trimTier != "none" {
- throw ValidationError("--trim applies to vm create: files are trimmed during its cfw install, before the setup boot.")
+ var wanted = try slimming.resolve()
+ // The setup boot trims nothing. A machine is trimmed beforehand by
+ // vm template trim, which records its tier; this boot's snapshot
+ // deletion is what frees it. --trim here only states what the caller
+ // expects that record to say.
+ let trimmed = try VPhoneMachineTemplates.readRecord(inBundle: bundle.url)?.steps.trimTier ?? "none"
+ let request = try slimming.request
+ if request.trimTier != nil || request.keepLanguages != nil, wanted.trimTier != trimmed {
+ throw ValidationError(
+ "\(target) is trimmed \(trimmed), not \(wanted.trimTier). The setup boot trims nothing: "
+ + "stop it and run vm template trim \(target) first, or leave --trim out.",
+ )
}
+ if trimmed == "none" {
+ print("note: \(target) is not trimmed; vm template trim \(target) before this boot frees about 1.2 GB")
+ }
+ wanted.trimTier = trimmed
// Checked before booting: a machine adopt would refuse is not worth it.
let recorded = try VPhoneMachineTemplateKeys.recorded(bundle)
if let snapshots = try? VPhoneMachineSnapshots.list(of: bundle), !snapshots.isEmpty {
@@ -271,6 +301,16 @@ struct VPhoneVirtualMachineTemplateSetupCommand: ParsableCommand {
throw ValidationError("\(target) is built to its key: \(record.key.slimming.summary). Leave the slimming switches out.")
}
}
+ if record.steps.trimTier != record.key.slimming.trimTier {
+ // The build stopped in or before its offline trim: finish that
+ // first, as vm create would have, before the snapshot goes.
+ try VPhoneMachineTemplateTrimmer.trim(
+ VPhoneBundle.load(at: build.bundleURL),
+ label: target,
+ spec: VPhoneSystemTrimSpec(keyValue: record.key.slimming.trimTier),
+ newRecord: nil,
+ )
+ }
if !record.steps.setupDone {
try VPhoneTemplateSetupRun.run(
bundleURL: build.bundleURL,
@@ -339,6 +379,9 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
sourceMachine: name,
steps: steps,
)
+ if let tree = VPhoneMachineTemplates.restoreTree(of: bundle) {
+ print("[*] Removing the restore tree \(tree)/: a template never keeps it")
+ }
let template = try VPhoneMachineTemplates.adopt(machineNamed: name, in: lib.library, record: record)
print("adopted \(name) as template \(template.identifier)")
print(" \(template.key.summary)")
@@ -346,6 +389,86 @@ struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {
}
}
+// MARK: - trim
+
+struct VPhoneVirtualMachineTemplateTrimCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "trim",
+ abstract: "Delete a trim tier's files from a stopped machine that is being built into a template",
+ discussion: """
+ Attaches the machine's Disk.img, mounts its guest System volume read-write (no root \
+ needed), deletes the tier's files and records the trim in its Template.plist, so \
+ vm template adopt keys the template by it. The target is a stopped VM of the library \
+ that will be adopted, or a .building-… folder from vm template list that no build holds.
+
+ Tiers: none; conservative (usr/standalone/update); standard (conservative, plus the \
+ AirPods/Beats pairing assets, the watch faces, and the linguistic data of languages not \
+ kept: --keep-languages, default en,zh-Hans,zh; English is always kept). aggressive is \
+ reserved and refused.
+
+ The deleted files stay allocated until the guest deletes its orig-fs snapshot during \
+ the template's setup boot, and a trimmed template is frozen only after that. Trimming \
+ cannot be undone: a machine already trimmed only takes the same trim again or a heavier \
+ one after conservative. Refused for a running machine, a frozen template, and a machine \
+ cloned from a template.
+ """,
+ )
+
+ @OptionGroup var lib: VPhoneLibraryOption
+ @Argument(help: "VM name, or a .building-… name from vm template list") var target: String
+ @Option(help: "Trim tier: none | conservative | standard") var tier = "standard"
+ @Option(help: ArgumentHelp("Languages whose linguistic data the standard tier keeps", valueName: "en,zh-Hans,zh"))
+ var keepLanguages: String?
+ @Flag(name: .shortAndLong, help: "Emit JSON") var json = false
+
+ func run() throws {
+ let spec = try VPhoneSystemTrimSpec.parse(tier: tier, keptLanguages: keepLanguages)
+ let library = lib.library
+ let bundle: VPhoneBundle
+ var newRecord: VPhoneMachineTemplateRecord?
+ if target.hasPrefix(".building-") {
+ guard let staging = try VPhoneMachineTemplates.list(in: library).staging.first(where: { $0.name == target }),
+ let identifier = staging.identifier
+ else {
+ throw VPhoneMachineTemplateError.notFound(target)
+ }
+ guard !staging.isActive else {
+ throw VPhoneMachineTemplateError.busy(identifier: identifier)
+ }
+ bundle = try VPhoneBundle.load(at: staging.url.appendingPathComponent(identifier, isDirectory: true))
+ } else {
+ bundle = try library.bundle(named: target)
+ if try VPhoneMachineTemplates.readRecord(inBundle: bundle.url) == nil {
+ // Resolved before anything is deleted: a machine without a
+ // finished CFW install or its records cannot become a template.
+ let recorded = try VPhoneMachineTemplateKeys.recorded(bundle)
+ newRecord = VPhoneMachineTemplateRecord(
+ key: recorded.key,
+ builtWithBundleVersion: VPhoneBundleVersion.current(),
+ bootChainBundleVersion: recorded.bootChainBundleVersion,
+ sourceMachine: target,
+ )
+ }
+ }
+ let result = try VPhoneMachineTemplateTrimmer.trim(
+ bundle,
+ label: target,
+ spec: spec,
+ newRecord: newRecord,
+ log: { line in
+ if json {
+ FileHandle.standardError.write(Data((line + "\n").utf8))
+ } else {
+ print(line)
+ }
+ },
+ )
+ if json {
+ try print(encodeJSON(result))
+ }
+ }
+}
+
// MARK: - delete
struct VPhoneVirtualMachineTemplateDeleteCommand: ParsableCommand {
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift
index 5991c192..2f3e1795 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift
@@ -381,6 +381,9 @@ public enum VPhoneBundleOperations {
VPhoneMachineSnapshots.directoryName,
".snapshot-revert-*",
VPhoneDiskRebase.stagingPrefix + "*",
+ // An imported machine is a full copy that shares no block with the
+ // template its source was cloned from.
+ VPhoneMachineTemplates.sourceFileName,
]
/// The directory holding each boot-chain file exactly as the restore tree laid
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleReport.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleReport.swift
index 1f62c3f8..05d503d7 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleReport.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleReport.swift
@@ -14,6 +14,9 @@ public struct VPhoneBundleReport: Codable, Equatable, Sendable {
/// present, so a client can tell a bundle that knows the setting from one
/// that does not.
public let unlocksAtStartup: Bool
+ /// The template the machine was cloned from (`TemplateSource.plist`),
+ /// or nil.
+ public let template: String?
/// Whether vphone-vm forwards the Mac's location to the guest. Always
/// present, like `unlocksAtStartup`.
public let syncsHostLocation: Bool
@@ -28,6 +31,7 @@ public struct VPhoneBundleReport: Codable, Equatable, Sendable {
customFirmwareInstalled = VPhoneRestoreInfo.customFirmwareInstalled(inBundle: bundle)
udid = VPhoneRestoreOperations.resolveUDID(bundle: bundle)
unlocksAtStartup = bundle.manifest.unlocksScreenAtStartup
+ template = VPhoneMachineTemplates.readSource(inBundle: bundle.url)?.identifier
syncsHostLocation = bundle.manifest.sharesHostLocation
}
}
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift
index b774ca40..9801fd99 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift
@@ -12,8 +12,9 @@ import Foundation
/// `serviceGroups` and `removedApps` (see `VPhoneTemplateSetupBoot`). What a
/// `vm create` asks for comes from its switches (`VPhoneTemplateSlimmingRequest`).
public struct VPhoneMachineTemplateSlimming: Codable, Equatable, Hashable, Sendable {
- /// The file-trimming tier applied to the System volume: `none`,
- /// `conservative`, `standard` or `aggressive`.
+ /// The file trim applied to the System volume, as
+ /// ``VPhoneSystemTrimSpec/keyValue`` writes it: `none`, `conservative/1`,
+ /// `standard/1/en,zh,zh-Hans` (tier, list version, kept languages).
public var trimTier: String
/// Whether the template was booted once to finish Setup and first-boot
/// work before it was frozen.
@@ -30,6 +31,16 @@ public struct VPhoneMachineTemplateSlimming: Codable, Equatable, Hashable, Senda
public static let none = VPhoneMachineTemplateSlimming()
+ /// Why a template could not be built with this slimming, or nothing. A
+ /// trim needs the setup boot: only the guest can delete the `orig-fs`
+ /// snapshot that otherwise keeps every trimmed block (see
+ /// ``VPhoneMachineTemplateSteps/problems``).
+ public var problems: [String] {
+ trimTier != "none" && !setupBoot
+ ? ["trim \(trimTier) needs the setup boot, which deletes the guest's orig-fs snapshot; without it the trim frees nothing"]
+ : []
+ }
+
public init(
trimTier: String = "none",
setupBoot: Bool = false,
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
index 1e9071f9..39b06030 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift
@@ -6,7 +6,7 @@ import Foundation
/// What was done to a template's guest after `cfw install` and before it was
/// frozen. Each later stage records its own work here while the template is
/// still being built (see ``VPhoneMachineTemplates/recordSteps(inBundle:_:)``):
-/// offline trimming inside the CFW install sets `trimTier`, the setup boot sets
+/// the offline trim after the CFW install sets `trimTier`, the setup boot sets
/// the rest. A template is frozen only when these match what its key promises.
public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
/// The guest's `orig-fs` APFS snapshot was deleted, so trimmed files free
@@ -37,6 +37,25 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
self.trimTier = trimTier
}
+ /// Why a template with these steps must not be frozen, or nothing.
+ ///
+ /// A trim with the `orig-fs` snapshot still in place is refused rather
+ /// than warned about: the snapshot keeps every deleted block, so such a
+ /// template costs exactly what an untrimmed one does while its clones
+ /// have lost the files, and its key would promise savings it never made.
+ /// Refusing keeps every frozen template either trimmed and smaller, or
+ /// untrimmed and whole.
+ public var problems: [String] {
+ var problems: [String] = []
+ if trimTier != "none", !snapshotDeleted {
+ problems.append(
+ "trim \(trimTier) frees nothing while the guest's orig-fs snapshot exists; "
+ + "the setup boot deletes it (apfs.snapshot.delete)",
+ )
+ }
+ return problems
+ }
+
/// The slimming these steps produced, as a key states it.
public var slimming: VPhoneMachineTemplateSlimming {
VPhoneMachineTemplateSlimming(
@@ -68,6 +87,25 @@ public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
}
}
+// MARK: - Source
+
+/// `TemplateSource.plist`, in a machine cloned from a template: which
+/// template it shares blocks with.
+public struct VPhoneMachineTemplateSource: Codable, Equatable, Sendable {
+ public var identifier: String
+ public var cloned: Date
+
+ public init(identifier: String, cloned: Date = Date()) {
+ self.identifier = identifier
+ self.cloned = VPhoneMachineTemplates.wholeSeconds(cloned)
+ }
+
+ private enum CodingKeys: String, CodingKey {
+ case identifier = "Identifier"
+ case cloned = "Cloned"
+ }
+}
+
// MARK: - Record
/// `Template.plist`, in the template's machine folder.
@@ -304,8 +342,22 @@ public enum VPhoneMachineTemplates {
/// Changes the build steps of a template that is still being built. A
/// frozen template is refused: it is shared by its clones, and nothing
/// may change it.
- public static func recordSteps(inBundle url: URL, _ body: (inout VPhoneMachineTemplateSteps) -> Void) throws {
- guard var record = try readRecord(inBundle: url) else {
+ ///
+ /// A machine without a record (one Launchpad is building in the library
+ /// before it adopts it) gets the unfrozen record `creating` returns
+ /// first; without `creating` it is refused.
+ public static func recordSteps(
+ inBundle url: URL,
+ creating: (() throws -> VPhoneMachineTemplateRecord)? = nil,
+ _ body: (inout VPhoneMachineTemplateSteps) -> Void,
+ ) throws {
+ var existing = try readRecord(inBundle: url)
+ if existing == nil, let creating {
+ existing = try creating()
+ existing?.frozen = false
+ existing?.frozenAt = nil
+ }
+ guard var record = existing else {
throw VPhoneMachineTemplateError.notBeingBuilt(path: url.path)
}
guard !record.frozen else {
@@ -480,8 +532,10 @@ public enum VPhoneMachineTemplates {
/// Marks the built machine frozen and moves it to `.templates/<identifier>`
/// in one rename, so a listed template is always complete. Refused when
- /// its steps did not produce what its key promises, or a template with
- /// the identifier appeared meanwhile; the build is then left in place.
+ /// its steps did not produce what its key promises or left a trim without
+ /// its snapshot deletion (``VPhoneMachineTemplateSteps/problems``), or a
+ /// template with the identifier appeared meanwhile; the build is then
+ /// left in place. The restore tree is removed: templates never keep it.
@discardableResult
public static func freeze(_ build: VPhoneMachineTemplateBuild, now: Date = Date()) throws -> VPhoneMachineTemplate {
guard var record = try readRecord(inBundle: build.bundleURL) else {
@@ -496,8 +550,12 @@ public enum VPhoneMachineTemplates {
differences: record.key.slimmingDifferences(from: record.steps.slimming),
)
}
+ guard record.steps.problems.isEmpty else {
+ throw VPhoneMachineTemplateError.incomplete(identifier: build.identifier, problems: record.steps.problems)
+ }
let bundle = try VPhoneBundle.load(at: build.bundleURL)
try VPhoneBundleActivity.requireStopped(bundle)
+ try removeRestoreTree(of: bundle)
record.frozen = true
record.frozenAt = Self.wholeSeconds(now)
try writeRecord(record, inBundle: build.bundleURL)
@@ -530,8 +588,10 @@ public enum VPhoneMachineTemplates {
///
/// Refused when the machine runs, has snapshots (a template carries no
/// history, and they would keep their blocks for as long as it lives),
- /// or a template with that key exists. On a failure the machine is left
- /// as it was.
+ /// its steps fall short of the key or have problems, or a template with
+ /// that key exists. On a failure the machine is left as it was, except
+ /// that a restore tree it kept is removed before the rename: templates
+ /// never keep it.
@discardableResult
public static func adopt(
machineNamed name: String,
@@ -563,11 +623,17 @@ public enum VPhoneMachineTemplates {
differences: record.key.slimmingDifferences(from: record.steps.slimming),
)
}
+ guard record.steps.problems.isEmpty else {
+ throw VPhoneMachineTemplateError.incomplete(identifier: record.identifier, problems: record.steps.problems)
+ }
let destination = url(of: record.identifier, in: library)
if isDirectory(destination) {
throw VPhoneMachineTemplateError.alreadyExists(record.identifier)
}
try ensureDirectory(in: library)
+ // Gone even if the rename below fails: it is only ever rebuilt from
+ // the IPSW, and a template must not carry it.
+ try removeRestoreTree(of: bundle)
record.frozen = true
record.frozenAt = Self.wholeSeconds(now)
try writeRecord(record, inBundle: bundle.url)
@@ -603,13 +669,108 @@ public enum VPhoneMachineTemplates {
in library: VPhoneLibrary,
) throws -> VPhoneBundle {
let source = try template.bundle()
- return try VPhoneBundleOperations.clone(
+ let clone = try VPhoneBundleOperations.clone(
source,
sourceName: template.record.sourceMachine ?? template.identifier,
to: newName,
in: library,
newIdentity: true,
)
+ do {
+ try writeSource(VPhoneMachineTemplateSource(identifier: template.identifier), inBundle: clone.url)
+ } catch {
+ try? FileManager.default.removeItem(at: clone.url)
+ throw error
+ }
+ return clone
+ }
+
+ // MARK: Source
+
+ /// `TemplateSource.plist`, in a machine cloned from a template. A plain
+ /// `vm clone` of such a machine keeps it (the copy shares the template's
+ /// blocks too); an export leaves it out, since an imported machine
+ /// shares nothing with any template.
+ public static let sourceFileName = "TemplateSource.plist"
+
+ /// The template a machine was cloned from, or nil for a machine that was
+ /// not, or whose record cannot be read.
+ public static func readSource(inBundle url: URL) -> VPhoneMachineTemplateSource? {
+ let file = url.appendingPathComponent(sourceFileName)
+ guard VPhoneVirtualMachineManifest.fileKind(at: file) == .regularFile,
+ let data = try? Data(contentsOf: file),
+ let source = try? PropertyListDecoder().decode(VPhoneMachineTemplateSource.self, from: data),
+ VPhoneMachineTemplateKey.isIdentifier(source.identifier)
+ else { return nil }
+ return source
+ }
+
+ static func writeSource(_ source: VPhoneMachineTemplateSource, inBundle url: URL) throws {
+ let encoder = PropertyListEncoder()
+ encoder.outputFormat = .xml
+ let file = url.appendingPathComponent(sourceFileName)
+ try encoder.encode(source).write(to: file, options: .atomic)
+ try VPhoneHostFilePermissions.makeAccessible(at: file)
+ }
+
+ /// The machines of the library cloned from each template, by template
+ /// identifier, sorted by name. Templates adopted from such a machine
+ /// count too, under `.templates/<id>`: they share its blocks as well.
+ public static func usage(in library: VPhoneLibrary) -> [String: [String]] {
+ var users: [String: [String]] = [:]
+ for bundle in (try? library.bundles()) ?? [] {
+ if let source = readSource(inBundle: bundle.url) {
+ users[source.identifier, default: []].append(bundle.name)
+ }
+ }
+ for template in (try? list(in: library).templates) ?? [] {
+ if let source = readSource(inBundle: template.url), source.identifier != template.identifier {
+ users[source.identifier, default: []].append("\(directoryName)/\(template.identifier)")
+ }
+ }
+ return users.mapValues { $0.sorted() }
+ }
+
+ /// The template `source` names, when it still exists and nothing in the
+ /// library uses it any more: what `vm delete` reports after deleting a
+ /// machine cloned from it. Never deletes it.
+ public static func unusedTemplate(after source: VPhoneMachineTemplateSource?, in library: VPhoneLibrary) -> VPhoneMachineTemplate? {
+ guard let source,
+ let template = try? Self.template(source.identifier, in: library),
+ usage(in: library)[template.identifier, default: []].isEmpty
+ else { return nil }
+ return template
+ }
+
+ /// The bytes a folder's files take on disk (`st_blocks`), without
+ /// following links: what deleting it would free once nothing shares it.
+ public static func allocatedBytes(of url: URL) -> UInt64 {
+ var total: UInt64 = 0
+ let keys: [URLResourceKey] = [.totalFileAllocatedSizeKey, .isSymbolicLinkKey]
+ guard let walker = FileManager.default.enumerator(at: url, includingPropertiesForKeys: keys, options: []) else {
+ return 0
+ }
+ for case let file as URL in walker {
+ guard let values = try? file.resourceValues(forKeys: Set(keys)), values.isSymbolicLink != true else { continue }
+ total += UInt64(values.totalFileAllocatedSize ?? 0)
+ }
+ return total
+ }
+
+ // MARK: Restore tree
+
+ /// Templates never keep the restore tree: the ~11 GB of prepared
+ /// firmware a full `cfw install` reads would stay pinned for as long as
+ /// the template lives, and no clone can use it. `freeze` and `adopt`
+ /// remove it. Returns the folder's name, or nil when there was none.
+ @discardableResult
+ public static func removeRestoreTree(of bundle: VPhoneBundle) throws -> String? {
+ try VPhoneRestoreInfo.removeBuiltFirmware(fromBundle: bundle)
+ }
+
+ /// The restore tree's name in a machine folder, or nil.
+ public static func restoreTree(of bundle: VPhoneBundle) -> String? {
+ (try? VPhoneConfinedDirectory(root: bundle.url.path)).flatMap(VPhoneRestoreInfo.findRestoreDirectory(in:))
}
// MARK: Delete
@@ -727,6 +888,7 @@ public enum VPhoneMachineTemplateError: Error, Equatable {
case notBeingBuilt(path: String)
case hasSnapshots(machine: String, count: Int)
case stepsDoNotMatchKey(identifier: String, differences: [String])
+ case incomplete(identifier: String, problems: [String])
case conflicts(identifier: String, options: [String])
case stale(identifier: String, reasons: [String])
case failed(path: String, reason: String)
@@ -757,6 +919,8 @@ extension VPhoneMachineTemplateError: CustomStringConvertible, LocalizedError {
"VM '\(machine)' has \(count) snapshot(s). A template carries no history: delete them with vm snapshot delete, then adopt it."
case let .stepsDoNotMatchKey(identifier, differences):
"Template \(identifier) was not built as its key says (\(differences.joined(separator: "; "))). It was not frozen."
+ case let .incomplete(identifier, problems):
+ "Template \(identifier) is not finished: \(problems.joined(separator: "; ")). It was not frozen."
case let .conflicts(identifier, options):
"Template \(identifier) cannot give this machine what was asked: \(options.joined(separator: "; ")). Use another template, or create the machine without one (--no-template)."
case let .stale(identifier, reasons):
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneSystemTrim.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneSystemTrim.swift
new file mode 100644
index 00000000..1645e8b3
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneSystemTrim.swift
@@ -0,0 +1,504 @@
+import Darwin
+import Foundation
+
+// MARK: - Tier
+
+/// How much of the guest's System volume a template build deletes offline,
+/// after `cfw install`. Each tier removes everything the one before it does.
+///
+/// The files go for good: a clone cannot get them back, so the tier is part
+/// of the template key. They also free nothing while the CFW-renamed
+/// `orig-fs.disabled.rn-*` snapshot still references them, and only the guest
+/// can delete that snapshot (vphoned `apfs.snapshot.delete`, during the
+/// template's setup boot). A trimmed template is therefore frozen only once
+/// its snapshot is gone; see ``VPhoneMachineTemplateSteps/problems``.
+public enum VPhoneSystemTrimTier: String, CaseIterable, Comparable, Sendable {
+ case none
+ /// `usr/standalone/update`: the software-update ramdisk and baseband
+ /// firmware. About 0.35 GB.
+ case conservative
+ /// Conservative, plus the AirPods/Beats pairing assets, the watch faces
+ /// and the linguistic data of languages not kept. About 1.2 GB.
+ case standard
+ /// Reserved: other languages' `.lproj`, Health assets, some fonts. Not
+ /// validated on a guest, so not offered.
+ case aggressive
+
+ /// Whether this version can apply the tier.
+ public var isSupported: Bool {
+ self != .aggressive
+ }
+
+ private var rank: Int {
+ Self.allCases.firstIndex(of: self) ?? 0
+ }
+
+ public static func < (lhs: Self, rhs: Self) -> Bool {
+ lhs.rank < rhs.rank
+ }
+
+ /// Parses a tier a user typed. `aggressive` is recognized and refused.
+ public static func parse(_ text: String) throws -> Self {
+ guard let tier = Self(rawValue: text.lowercased()) else {
+ throw VPhoneSystemTrimError.unknownTier(text)
+ }
+ guard tier.isSupported else {
+ throw VPhoneSystemTrimError.unsupportedTier(tier.rawValue)
+ }
+ return tier
+ }
+}
+
+// MARK: - Entry
+
+/// One place on the System volume a tier deletes from.
+public struct VPhoneSystemTrimEntry: Equatable, Sendable {
+ public enum Selection: Equatable, Sendable {
+ /// The item at `path` itself.
+ case item
+ /// Everything inside the folder at `path`; the folder stays.
+ case contents
+ /// The children of the folder at `path` named `prefix + language +
+ /// suffix` whose language is not in `keeping`. Other children stay.
+ case languageBundles(prefix: String, suffix: String, keeping: [String])
+ }
+
+ /// Relative to the System volume's root.
+ public let path: String
+ public let selection: Selection
+ /// The lowest tier that deletes it.
+ public let tier: VPhoneSystemTrimTier
+ /// Why it can go, for logs and docs.
+ public let note: String
+
+ /// Whether a direct child of the folder at `path`, by name, is deleted.
+ /// Never for `.item`, which names its target itself.
+ public func selects(child name: String) -> Bool {
+ guard VPhoneSystemTrim.isSingleComponent(name) else { return false }
+ switch selection {
+ case .item:
+ return false
+ case .contents:
+ return true
+ case let .languageBundles(prefix, suffix, keeping):
+ guard name.hasPrefix(prefix), name.hasSuffix(suffix), name.count > prefix.count + suffix.count else {
+ return false
+ }
+ let language = String(name.dropFirst(prefix.count).dropLast(suffix.count))
+ return !keeping.contains(language)
+ }
+ }
+}
+
+// MARK: - Spec
+
+/// One trim: a tier, the version of the list it was taken from, and the
+/// languages a language-removing tier keeps. ``keyValue`` is what a template
+/// key and its recorded steps store as `trimTier`, so templates trimmed by a
+/// different list or keeping other languages never match each other.
+public struct VPhoneSystemTrimSpec: Equatable, Hashable, Sendable {
+ public let tier: VPhoneSystemTrimTier
+ public let listVersion: Int
+ /// Sorted. Empty for a tier that removes no language data.
+ public let keptLanguages: [String]
+
+ public static let none = VPhoneSystemTrimSpec(uncheckedTier: .none, listVersion: VPhoneSystemTrim.listVersion, keptLanguages: [])
+
+ /// The standard tier keeping ``VPhoneSystemTrim/defaultKeptLanguages``:
+ /// the default for a template that gets its setup boot.
+ public static let standard = VPhoneSystemTrimSpec(
+ uncheckedTier: .standard,
+ listVersion: VPhoneSystemTrim.listVersion,
+ keptLanguages: Array(Set(VPhoneSystemTrim.defaultKeptLanguages + ["en"])).sorted(),
+ )
+
+ /// `--trim` and `--keep-languages` as typed: a tier name, and an optional
+ /// comma-separated language list, which only a language-removing tier
+ /// takes.
+ public static func parse(tier text: String, keptLanguages list: String? = nil) throws -> Self {
+ let tier = try VPhoneSystemTrimTier.parse(text)
+ guard let list else { return try Self(tier: tier) }
+ guard tier >= .standard else {
+ throw VPhoneSystemTrimError.languagesUnused(tier.rawValue)
+ }
+ let languages = list.split(separator: ",").map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }
+ return try Self(tier: tier, keptLanguages: languages)
+ }
+
+ /// Validates the tier and languages. English is always kept.
+ public init(tier: VPhoneSystemTrimTier, keptLanguages: [String] = VPhoneSystemTrim.defaultKeptLanguages) throws {
+ guard tier.isSupported else {
+ throw VPhoneSystemTrimError.unsupportedTier(tier.rawValue)
+ }
+ for language in keptLanguages where !VPhoneSystemTrim.isLanguageIdentifier(language) {
+ throw VPhoneSystemTrimError.invalidLanguage(language)
+ }
+ let removesLanguages = tier >= .standard
+ self.init(
+ uncheckedTier: tier,
+ listVersion: VPhoneSystemTrim.listVersion,
+ keptLanguages: removesLanguages ? Array(Set(keptLanguages + ["en"])).sorted() : [],
+ )
+ }
+
+ private init(uncheckedTier tier: VPhoneSystemTrimTier, listVersion: Int, keptLanguages: [String]) {
+ self.tier = tier
+ self.listVersion = listVersion
+ self.keptLanguages = keptLanguages
+ }
+
+ /// `none`, `conservative/1`, `standard/1/en,zh,zh-Hans`.
+ public var keyValue: String {
+ guard tier != .none else { return "none" }
+ var parts = [tier.rawValue, String(listVersion)]
+ if !keptLanguages.isEmpty {
+ parts.append(keptLanguages.joined(separator: ","))
+ }
+ return parts.joined(separator: "/")
+ }
+
+ /// Reads a ``keyValue`` back. Only the current list version can be
+ /// applied; an older one is still a valid key, but no longer a trim.
+ public init(keyValue: String) throws {
+ let parts = keyValue.split(separator: "/", omittingEmptySubsequences: false).map(String.init)
+ guard let tier = VPhoneSystemTrimTier(rawValue: parts[0]) else {
+ throw VPhoneSystemTrimError.unknownTier(keyValue)
+ }
+ if tier == .none {
+ guard parts.count == 1 else { throw VPhoneSystemTrimError.unknownTier(keyValue) }
+ self = .none
+ return
+ }
+ guard parts.count >= 2, let version = Int(parts[1]) else {
+ throw VPhoneSystemTrimError.unknownTier(keyValue)
+ }
+ guard version == VPhoneSystemTrim.listVersion else {
+ throw VPhoneSystemTrimError.unavailableListVersion(version)
+ }
+ let languages = parts.count > 2 ? parts[2].split(separator: ",").map(String.init) : []
+ try self.init(tier: tier, keptLanguages: languages)
+ guard self.keyValue == keyValue else {
+ throw VPhoneSystemTrimError.unknownTier(keyValue)
+ }
+ }
+
+ /// The tier named by a `trimTier` value, whatever its list version.
+ public static func tier(ofKeyValue value: String) -> VPhoneSystemTrimTier? {
+ value.split(separator: "/", maxSplits: 1).first.flatMap { VPhoneSystemTrimTier(rawValue: String($0)) }
+ }
+
+ /// Whether a machine whose steps record `recorded` may take this trim.
+ /// A trim cannot be undone, so only `none` to anything, the same trim
+ /// again (which deletes whatever is left), or conservative to a heavier
+ /// tier, which contains it.
+ public func canFollow(recorded: String) -> Bool {
+ if recorded == "none" || recorded == keyValue {
+ return true
+ }
+ guard let previous = Self.tier(ofKeyValue: recorded) else { return false }
+ return previous == .conservative && tier > .conservative
+ }
+
+ /// The entries this trim deletes, in the order they are applied.
+ public var entries: [VPhoneSystemTrimEntry] {
+ VPhoneSystemTrim.entries(keptLanguages: keptLanguages).filter { tier != .none && $0.tier <= tier }
+ }
+
+ /// Whether deleting `relative` (a path on the System volume) is part of
+ /// this trim: one of its `.item` paths, or a direct child its entry
+ /// selects. Everything the trim deletes passes this check first.
+ public func permits(_ relative: String) -> Bool {
+ guard VPhoneSystemTrim.isSafeRelativePath(relative) else { return false }
+ for entry in entries {
+ switch entry.selection {
+ case .item:
+ if relative == entry.path { return true }
+ case .contents, .languageBundles:
+ let prefix = entry.path + "/"
+ guard relative.hasPrefix(prefix) else { continue }
+ let child = String(relative.dropFirst(prefix.count))
+ if entry.selects(child: child) { return true }
+ }
+ }
+ return false
+ }
+}
+
+// MARK: - Lists
+
+public enum VPhoneSystemTrim {
+ /// Raised whenever an entry is added, removed or changes what it
+ /// selects. Part of ``VPhoneSystemTrimSpec/keyValue``.
+ public static let listVersion = 1
+
+ /// The languages the standard tier keeps by default: English, and the
+ /// Simplified Chinese bundle with the `zh` bundle it shares data with.
+ public static let defaultKeptLanguages = ["en", "zh-Hans", "zh"]
+
+ /// List version 1, measured on iPhone17,3 iOS 27.0 (24A435) and booted
+ /// after deletion (see `Research/Host/machine_templates.md`). Never on
+ /// the list: the dyld shared cache and its `.symbols` (CFW's cache
+ /// patcher resolves symbols from it), ML models, `/Applications`.
+ static func entries(keptLanguages: [String]) -> [VPhoneSystemTrimEntry] {
+ [
+ VPhoneSystemTrimEntry(
+ path: "usr/standalone/update",
+ selection: .contents,
+ tier: .conservative,
+ note: "software-update ramdisk and baseband firmware; a VM has no baseband and OTA is blocked",
+ ),
+ VPhoneSystemTrimEntry(
+ path: "System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets",
+ selection: .item,
+ tier: .standard,
+ note: "AirPods and Beats pairing artwork",
+ ),
+ VPhoneSystemTrimEntry(
+ path: "System/Library/NanoTimeKit/FaceBundles",
+ selection: .contents,
+ tier: .standard,
+ note: "Apple Watch faces; a VM pairs no watch",
+ ),
+ VPhoneSystemTrimEntry(
+ path: "System/Library/LinguisticData",
+ selection: .languageBundles(prefix: "RequiredAssets_", suffix: ".bundle", keeping: keptLanguages),
+ tier: .standard,
+ note: "linguistic data of languages not kept",
+ ),
+ ]
+ }
+
+ /// A file on the System volume that only an iOS System volume has,
+ /// checked before anything is deleted.
+ public static let systemVolumeMarker = "System/Library/CoreServices/SystemVersion.plist"
+
+ // MARK: Path rules
+
+ /// Non-empty, relative, no empty, `.` or `..` component, no NUL.
+ public static func isSafeRelativePath(_ path: String) -> Bool {
+ guard !path.isEmpty, !path.hasPrefix("/"), !path.contains("\0") else { return false }
+ return path.split(separator: "/", omittingEmptySubsequences: false).allSatisfy {
+ isSingleComponent(String($0))
+ }
+ }
+
+ static func isSingleComponent(_ name: String) -> Bool {
+ !name.isEmpty && name != "." && name != ".." && !name.contains("/") && !name.contains("\0")
+ }
+
+ /// `en`, `zh-Hans`, `pt_BR`: letters, digits, `-` and `_`, up to 16.
+ public static func isLanguageIdentifier(_ text: String) -> Bool {
+ (1 ... 16).contains(text.utf8.count) && text.utf8.allSatisfy { byte in
+ (byte >= 0x30 && byte <= 0x39) || (byte >= 0x41 && byte <= 0x5A)
+ || (byte >= 0x61 && byte <= 0x7A) || byte == 0x2D || byte == 0x5F
+ }
+ }
+}
+
+// MARK: - Applying
+
+/// What a trim deleted from one entry.
+public struct VPhoneSystemTrimEntryResult: Codable, Equatable, Sendable {
+ public var path: String
+ /// Names deleted: the item itself, or the selected children.
+ public var removed: [String]
+ /// Allocated bytes of what was deleted (`st_blocks`), counting a file
+ /// with more than one hard link as nothing.
+ public var bytes: UInt64
+ /// The entry's path did not exist (already trimmed, or another release).
+ public var absent: Bool
+}
+
+public struct VPhoneSystemTrimResult: Codable, Equatable, Sendable {
+ public var trim: String
+ public var entries: [VPhoneSystemTrimEntryResult]
+
+ public var bytes: UInt64 {
+ entries.reduce(0) { $0 + $1.bytes }
+ }
+
+ public init(trim: String, entries: [VPhoneSystemTrimEntryResult]) {
+ self.trim = trim
+ self.entries = entries
+ }
+
+ private enum CodingKeys: String, CodingKey {
+ case trim, entries, bytes
+ }
+
+ public init(from decoder: any Decoder) throws {
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ trim = try container.decode(String.self, forKey: .trim)
+ entries = try container.decode([VPhoneSystemTrimEntryResult].self, forKey: .entries)
+ }
+
+ /// With the total, for callers that read only that.
+ public func encode(to encoder: any Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ try container.encode(trim, forKey: .trim)
+ try container.encode(entries, forKey: .entries)
+ try container.encode(bytes, forKey: .bytes)
+ }
+}
+
+public extension VPhoneSystemTrimSpec {
+ /// Deletes this trim from a System volume opened at `root` (the mounted
+ /// volume's root, by descriptor). Nothing is followed: every path is
+ /// walked with `O_NOFOLLOW` and refused if it passes through a symbolic
+ /// link or leaves the volume, a link is deleted as a link, and each
+ /// deletion must be ``permits(_:)``-ed first. Refused outright when
+ /// `root` is not an iOS System volume.
+ func apply(to root: VPhoneConfinedDirectory, log: (String) -> Void = { _ in }) throws -> VPhoneSystemTrimResult {
+ guard (try? root.isRegularFile(VPhoneSystemTrim.systemVolumeMarker)) == true else {
+ throw VPhoneSystemTrimError.notSystemVolume
+ }
+ var results: [VPhoneSystemTrimEntryResult] = []
+ for entry in entries {
+ var result = VPhoneSystemTrimEntryResult(path: entry.path, removed: [], bytes: 0, absent: false)
+ switch entry.selection {
+ case .item:
+ guard try root.exists(entry.path) else {
+ result.absent = true
+ break
+ }
+ guard permits(entry.path) else { throw VPhoneSystemTrimError.notPermitted(entry.path) }
+ result.bytes = try root.removeItem(entry.path)
+ result.removed = [(entry.path as NSString).lastPathComponent]
+ case .contents, .languageBundles:
+ let folder: VPhoneConfinedDirectory
+ do {
+ folder = try root.directory(entry.path)
+ } catch VPhoneConfinedDirectoryError.missing {
+ result.absent = true
+ break
+ }
+ for child in try folder.entries() where entry.selects(child: child) {
+ let relative = "\(entry.path)/\(child)"
+ guard permits(relative) else { throw VPhoneSystemTrimError.notPermitted(relative) }
+ result.bytes += try folder.removeItem(child)
+ result.removed.append(child)
+ }
+ }
+ log(Self.describe(result))
+ results.append(result)
+ }
+ return VPhoneSystemTrimResult(trim: keyValue, entries: results)
+ }
+
+ static func describe(_ result: VPhoneSystemTrimEntryResult) -> String {
+ if result.absent {
+ return "\(result.path): not present"
+ }
+ let count = result.removed.count
+ return "\(result.path): removed \(count) item\(count == 1 ? "" : "s"), \(VPhoneSystemTrim.formatBytes(result.bytes))"
+ }
+}
+
+public extension VPhoneSystemTrim {
+ /// `353.2 MB`, decimal like the rest of the CLI's sizes.
+ static func formatBytes(_ bytes: UInt64) -> String {
+ if bytes >= 1_000_000_000 {
+ return String(format: "%.2f GB", Double(bytes) / 1_000_000_000)
+ }
+ return String(format: "%.1f MB", Double(bytes) / 1_000_000)
+ }
+}
+
+// MARK: - Disk layout
+
+/// Reading `hdiutil attach` and `diskutil` output to find a guest image's
+/// System volume by its APFS role, not by slice number.
+public enum VPhoneGuestDiskLayout {
+ /// The attached image's whole disk and its APFS physical store, from
+ /// `hdiutil attach -nomount` output (`/dev/disk6 GUID_partition_scheme`,
+ /// `/dev/disk6s1 Apple_APFS`, and on macOS 27 the synthesized
+ /// container's own lines, which are neither).
+ public static func attachedDisks(fromAttachOutput output: String) -> (wholeDisk: String?, store: String?) {
+ let devices = output.split(whereSeparator: \.isNewline).compactMap { line -> (device: String, type: String)? in
+ let fields = line.split(whereSeparator: \.isWhitespace)
+ guard fields.count >= 2, fields[0].hasPrefix("/dev/disk") else { return nil }
+ return (String(fields[0].dropFirst("/dev/".count)), String(fields[1]))
+ }
+ let store = devices.first(where: { $0.type == "Apple_APFS" })?.device
+ let whole = devices.first(where: { $0.type == "GUID_partition_scheme" })?.device
+ ?? store.flatMap { device in
+ device.range(of: "s", options: .backwards).map { String(device[..<$0.lowerBound]) }
+ }
+ return (whole, store)
+ }
+
+ /// The device of the one volume with the `System` role in `container`,
+ /// from `diskutil apfs list -plist <container>`, after checking the
+ /// container sits on `physicalStore` (the disk just attached, not
+ /// another container that happens to have the same number).
+ public static func systemVolume(fromAPFSList data: Data, container: String, physicalStore: String) throws -> String {
+ guard
+ let plist = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any],
+ let containers = plist["Containers"] as? [[String: Any]],
+ let entry = containers.first(where: { $0["ContainerReference"] as? String == container }),
+ let stores = entry["PhysicalStores"] as? [[String: Any]],
+ stores.contains(where: { $0["DeviceIdentifier"] as? String == physicalStore }),
+ let volumes = entry["Volumes"] as? [[String: Any]]
+ else {
+ throw VPhoneSystemTrimError.layout("the APFS container \(container) is not on the attached disk \(physicalStore)")
+ }
+ let systems = volumes.filter { ($0["Roles"] as? [String])?.contains("System") == true }
+ guard systems.count == 1, let device = systems[0]["DeviceIdentifier"] as? String,
+ device.hasPrefix("\(container)s"), isDeviceName(device)
+ else {
+ throw VPhoneSystemTrimError.layout("container \(container) has \(systems.count) System-role volumes, not one")
+ }
+ return device
+ }
+
+ /// `disk12s1`.
+ public static func isDeviceName(_ text: String) -> Bool {
+ text.range(of: #"^disk[0-9]+(s[0-9]+)?$"#, options: .regularExpression) != nil
+ }
+}
+
+// MARK: - Error
+
+public enum VPhoneSystemTrimError: Error, Equatable {
+ case unknownTier(String)
+ case unsupportedTier(String)
+ case invalidLanguage(String)
+ case languagesUnused(String)
+ case unavailableListVersion(Int)
+ case notSystemVolume
+ case notPermitted(String)
+ case layout(String)
+ case downgrade(machine: String, recorded: String, requested: String)
+ case clonedFromTemplate(machine: String, template: String)
+}
+
+extension VPhoneSystemTrimError: CustomStringConvertible, LocalizedError {
+ public var description: String {
+ switch self {
+ case let .unknownTier(text):
+ "'\(text)' is not a trim tier. Use none, conservative or standard."
+ case let .unsupportedTier(tier):
+ "Trim tier \(tier) is reserved and not supported yet: it has not been validated on a guest. Use none, conservative or standard."
+ case let .invalidLanguage(text):
+ "'\(text)' is not a language identifier (letters, digits, - and _, such as en or zh-Hans)."
+ case let .languagesUnused(tier):
+ "--keep-languages applies to the standard tier, which removes language data; \(tier) removes none."
+ case let .unavailableListVersion(version):
+ "Trim list version \(version) is not this vphone-cli's (\(VPhoneSystemTrim.listVersion)); it can no longer be applied."
+ case .notSystemVolume:
+ "The mounted volume is not an iOS System volume (no \(VPhoneSystemTrim.systemVolumeMarker)). Nothing was deleted."
+ case let .notPermitted(path):
+ "Refusing to delete \(path): it is not on the trim list."
+ case let .layout(reason):
+ "Cannot find the guest's System volume: \(reason)."
+ case let .downgrade(machine, recorded, requested):
+ "VM '\(machine)' is already trimmed (\(recorded)); a trim cannot be undone or narrowed, so it cannot take \(requested). Build another template for that."
+ case let .clonedFromTemplate(machine, template):
+ "VM '\(machine)' was cloned from template \(template) and shares its system files; trimming it would free nothing. Trim a template build instead."
+ }
+ }
+
+ public var errorDescription: String? {
+ description
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSlimmingRequest.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSlimmingRequest.swift
index eeac4101..a0d69a57 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSlimmingRequest.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneTemplateSlimmingRequest.swift
@@ -13,9 +13,12 @@ import Foundation
public struct VPhoneTemplateSlimmingRequest: Equatable, Sendable {
/// `--slim on|off`; nil is on.
public var slim: Bool?
- /// `--trim none|conservative|standard|aggressive` (offline file trim);
- /// nil is ``defaultTrimTier`` when slimming.
+ /// `--trim none|conservative|standard` (offline file trim, see
+ /// ``VPhoneSystemTrimSpec``); nil is ``defaultTrim`` when slimming.
public var trimTier: String?
+ /// `--keep-languages`: the languages a language-removing tier keeps.
+ /// Given alone it means the standard tier keeping these languages.
+ public var keepLanguages: String?
/// `--service-profile none|trimmed`; nil is trimmed when slimming.
public var serviceProfile: String?
/// `--remove-apps on|off`; nil is on when slimming.
@@ -28,6 +31,7 @@ public struct VPhoneTemplateSlimmingRequest: Equatable, Sendable {
public init(
slim: Bool? = nil,
trimTier: String? = nil,
+ keepLanguages: String? = nil,
serviceProfile: String? = nil,
removeApps: Bool? = nil,
keepApps: [String] = [],
@@ -35,6 +39,7 @@ public struct VPhoneTemplateSlimmingRequest: Equatable, Sendable {
) {
self.slim = slim
self.trimTier = trimTier
+ self.keepLanguages = keepLanguages
self.serviceProfile = serviceProfile
self.removeApps = removeApps
self.keepApps = keepApps
@@ -43,12 +48,18 @@ public struct VPhoneTemplateSlimmingRequest: Equatable, Sendable {
// MARK: Defaults
- /// The file-trim tier a slimmed template gets when `--trim` is not given.
- /// Offline trimming is not built yet, so it is `none`; it becomes
- /// `standard` with it.
- public static let defaultTrimTier = "none"
+ /// The file trim a slimmed template gets when `--trim` is not given: the
+ /// standard tier keeping ``VPhoneSystemTrim/defaultKeptLanguages``. The
+ /// setup boot deletes the orig-fs snapshot, which is what frees it.
+ public static let defaultTrim = VPhoneSystemTrimSpec.standard
- public static let trimTiers = ["none", "conservative", "standard", "aggressive"]
+ /// ``defaultTrim`` as the key stores it (`standard/1/en,zh,zh-Hans`).
+ public static var defaultTrimTier: String {
+ defaultTrim.keyValue
+ }
+
+ /// The tiers `--trim` takes. `aggressive` is reserved and refused.
+ public static let trimTiers = VPhoneSystemTrimTier.allCases.filter(\.isSupported).map(\.rawValue)
public static let serviceProfiles = ["none", "trimmed"]
/// The removable system apps a slimmed template drops (list C of the
@@ -89,8 +100,18 @@ public struct VPhoneTemplateSlimmingRequest: Equatable, Sendable {
/// each other.
public func resolve() throws -> VPhoneMachineTemplateSlimming {
var problems: [String] = []
- if let trimTier, !Self.trimTiers.contains(trimTier) {
- problems.append("--trim must be one of \(Self.trimTiers.joined(separator: ", ")), not \(trimTier)")
+ // --keep-languages alone means the standard tier keeping them.
+ var trim = slim == false ? VPhoneSystemTrimSpec.none : Self.defaultTrim
+ let trimGiven = trimTier != nil || keepLanguages != nil
+ if trimGiven {
+ do {
+ trim = try VPhoneSystemTrimSpec.parse(
+ tier: trimTier ?? VPhoneSystemTrimTier.standard.rawValue,
+ keptLanguages: keepLanguages,
+ )
+ } catch {
+ problems.append(String(describing: error))
+ }
}
if let serviceProfile, !Self.serviceProfiles.contains(serviceProfile) {
problems.append("--service-profile must be none or trimmed, not \(serviceProfile)")
@@ -105,7 +126,9 @@ public struct VPhoneTemplateSlimmingRequest: Equatable, Sendable {
if slim == false {
var contradicted: [String] = []
- if let trimTier, trimTier != "none" { contradicted.append("--trim \(trimTier)") }
+ if trimGiven, trim.tier != .none {
+ contradicted.append(trimTier.map { "--trim \($0)" } ?? "--keep-languages")
+ }
if serviceProfile == "trimmed" { contradicted.append("--service-profile trimmed") }
if removeApps == true { contradicted.append("--remove-apps on") }
if !keepApps.isEmpty { contradicted.append("--keep-apps") }
@@ -128,7 +151,7 @@ public struct VPhoneTemplateSlimmingRequest: Equatable, Sendable {
let keep = Set(keepApps)
return VPhoneMachineTemplateSlimming(
- trimTier: slim == false ? "none" : trimTier ?? Self.defaultTrimTier,
+ trimTier: trim.keyValue,
setupBoot: true,
serviceProfile: profile,
serviceGroups: accountsOff ? [Self.accountsGroup] : [],
diff --git a/VPhoneKit/VPhoneCoreKit/Process/VPhoneConfinedDirectory.swift b/VPhoneKit/VPhoneCoreKit/Process/VPhoneConfinedDirectory.swift
index 4a4a977a..0da784be 100644
--- a/VPhoneKit/VPhoneCoreKit/Process/VPhoneConfinedDirectory.swift
+++ b/VPhoneKit/VPhoneCoreKit/Process/VPhoneConfinedDirectory.swift
@@ -463,7 +463,7 @@ public final class VPhoneConfinedDirectory: Sendable {
/// Replace whatever is at `relative` with a symbolic link to `target`.
public func createSymlink(target: String, at relative: String) throws {
let (directory, leaf) = try parent(of: relative)
- try Self.removeEntry(in: directory.descriptor, named: leaf, device: directory.device, path: relative)
+ _ = try Self.removeEntry(in: directory.descriptor, named: leaf, device: directory.device, path: relative)
guard symlinkat(target, directory.descriptor, leaf) == 0 else {
throw VPhoneConfinedDirectoryError.from(errno, relative)
}
@@ -497,14 +497,17 @@ public final class VPhoneConfinedDirectory: Sendable {
/// Remove `relative` and everything below it without following a link:
/// a symbolic link is removed as a link. Absent is not an error. A folder
/// on another volume (something still mounted) is refused, not emptied.
- public func removeItem(_ relative: String) throws {
+ /// Returns the allocated bytes (`st_blocks`) of what was removed; a file
+ /// with a second hard link frees nothing and counts as nothing.
+ @discardableResult
+ public func removeItem(_ relative: String) throws -> UInt64 {
let parent: (directory: VPhoneConfinedDirectory, leaf: String)
do {
parent = try self.parent(of: relative)
} catch VPhoneConfinedDirectoryError.missing {
- return
+ return 0
}
- try Self.removeEntry(in: parent.directory.descriptor, named: parent.leaf, device: device, path: relative)
+ return try Self.removeEntry(in: parent.directory.descriptor, named: parent.leaf, device: device, path: relative)
}
// MARK: - Tree copy
@@ -660,19 +663,20 @@ public final class VPhoneConfinedDirectory: Sendable {
}
}
- private static func removeEntry(in parent: Int32, named name: String, device: dev_t, path: String) throws {
+ private static func removeEntry(in parent: Int32, named name: String, device: dev_t, path: String) throws -> UInt64 {
var metadata = stat()
guard fstatat(parent, name, &metadata, AT_SYMLINK_NOFOLLOW) == 0 else {
if errno == ENOENT {
- return
+ return 0
}
throw VPhoneConfinedDirectoryError.from(errno, path)
}
+ let allocated = metadata.st_nlink <= 1 ? UInt64(max(metadata.st_blocks, 0)) * 512 : 0
guard metadata.st_mode & S_IFMT == S_IFDIR else {
guard unlinkat(parent, name, 0) == 0 || errno == ENOENT else {
throw VPhoneConfinedDirectoryError.from(errno, path)
}
- return
+ return allocated
}
guard metadata.st_dev == device else {
throw VPhoneConfinedDirectoryError.crossesDevice(path)
@@ -692,12 +696,15 @@ public final class VPhoneConfinedDirectory: Sendable {
if opened.st_mode & 0o700 != 0o700 {
_ = fchmod(child, (opened.st_mode & 0o7777) | 0o700)
}
+ // A directory's own blocks; its hard link count is its subfolder count.
+ var removed = UInt64(max(opened.st_blocks, 0)) * 512
for entry in try entries(of: child, path: path) {
- try removeEntry(in: child, named: entry, device: device, path: "\(path)/\(entry)")
+ removed += try removeEntry(in: child, named: entry, device: device, path: "\(path)/\(entry)")
}
guard unlinkat(parent, name, AT_REMOVEDIR) == 0 || errno == ENOENT else {
throw VPhoneConfinedDirectoryError.from(errno, path)
}
+ return removed
}
}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
index 826ba48b..105aee05 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift
@@ -426,4 +426,141 @@ struct MachineTemplatesTests {
#expect(reasons[1].contains("kernel-x"))
#expect(template.staleReasons(currentSeries: "2.8", freshKey: nil).count == 1)
}
+
+ // MARK: - Trim and the snapshot
+
+ @Test func `a trim without its snapshot deletion is never frozen or adopted`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let trim = VPhoneSystemTrimSpec.standard.keyValue
+ let key = MachineTemplateKeyTests.key(slimming: .init(trimTier: trim, setupBoot: true))
+ let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
+ try makeMachine(key.identifier, in: fixture, library: build.library)
+ try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)
+ try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) {
+ $0.trimTier = trim
+ $0.setupDone = true
+ }
+
+ #expect(VPhoneMachineTemplateSteps(trimTier: trim).problems.count == 1)
+ #expect(throws: VPhoneMachineTemplateError.self) {
+ try VPhoneMachineTemplates.freeze(build)
+ }
+ #expect(try VPhoneMachineTemplates.readRecord(inBundle: build.bundleURL)?.frozen == false)
+
+ try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) { $0.snapshotDeleted = true }
+ #expect(try VPhoneMachineTemplates.freeze(build).record.steps.trimTier == trim)
+
+ // Adopt follows the same rule.
+ try makeMachine("src", in: fixture)
+ let adoptKey = MachineTemplateKeyTests.key(bootChain: "other", slimming: .init(trimTier: trim, setupBoot: true))
+ #expect(throws: VPhoneMachineTemplateError.self) {
+ try VPhoneMachineTemplates.adopt(
+ machineNamed: "src",
+ in: fixture.library,
+ record: record(adoptKey, steps: .init(setupDone: true, trimTier: trim)),
+ )
+ }
+ #expect(exists(fixture.library.url(forName: "src")))
+ #expect(VPhoneMachineTemplateSteps(snapshotDeleted: true, trimTier: trim).problems.isEmpty)
+ #expect(VPhoneMachineTemplateSteps().problems.isEmpty)
+ }
+
+ @Test func `a key asking for a trim needs the setup boot`() {
+ let trim = VPhoneSystemTrimSpec.standard.keyValue
+ #expect(VPhoneMachineTemplateSlimming(trimTier: trim).problems.count == 1)
+ #expect(VPhoneMachineTemplateSlimming(trimTier: trim, setupBoot: true).problems.isEmpty)
+ #expect(VPhoneMachineTemplateSlimming.none.problems.isEmpty)
+ }
+
+ @Test func `steps can be recorded on a library machine that has no record yet`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let machine = try makeMachine("src", in: fixture)
+ #expect(throws: VPhoneMachineTemplateError.notBeingBuilt(path: machine.url.path)) {
+ try VPhoneMachineTemplates.recordSteps(inBundle: machine.url) { $0.trimTier = "conservative/1" }
+ }
+ var frozen = record()
+ frozen.frozen = true
+ try VPhoneMachineTemplates.recordSteps(inBundle: machine.url, creating: { frozen }) { $0.trimTier = "conservative/1" }
+ let written = try #require(try VPhoneMachineTemplates.readRecord(inBundle: machine.url))
+ #expect(!written.frozen)
+ #expect(written.steps.trimTier == "conservative/1")
+ // It still boots: only a frozen record refuses.
+ #expect(VPhoneMachineTemplates.bootRefusal(bundleURL: machine.url) == nil)
+ }
+
+ // MARK: - Restore tree
+
+ @Test func `a template never keeps the restore tree`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let machine = try makeMachine("src", in: fixture)
+ let tree = machine.url.appendingPathComponent("iPhone17,3_27.0_24A435_Restore")
+ try FileManager.default.createDirectory(at: tree, withIntermediateDirectories: true)
+ try Data([1]).write(to: tree.appendingPathComponent("kernelcache"))
+ #expect(VPhoneMachineTemplates.restoreTree(of: machine) == tree.lastPathComponent)
+
+ let adopted = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
+ #expect(!exists(adopted.url.appendingPathComponent(tree.lastPathComponent)))
+ #expect(exists(adopted.url.appendingPathComponent("Disk.img")))
+
+ let key = MachineTemplateKeyTests.key(bootChain: "built")
+ let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
+ let built = try makeMachine(key.identifier, in: fixture, library: build.library)
+ try FileManager.default.createDirectory(at: built.url.appendingPathComponent("iPhone17,3_27.0_24A435_Restore"), withIntermediateDirectories: true)
+ try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)
+ let frozen = try VPhoneMachineTemplates.freeze(build)
+ #expect(VPhoneMachineTemplates.restoreTree(of: try frozen.bundle()) == nil)
+ }
+
+ // MARK: - Source and usage
+
+ @Test func `clones record their template, plain clones keep it, and the last one leaving is noticed`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ try makeMachine("src", in: fixture)
+ try makeMachine("own", in: fixture)
+ let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
+ #expect(VPhoneMachineTemplates.readSource(inBundle: template.url) == nil)
+
+ let a = try VPhoneMachineTemplates.cloneMachine(from: template, to: "phone-a", in: fixture.library)
+ #expect(VPhoneMachineTemplates.readSource(inBundle: a.url)?.identifier == template.identifier)
+ #expect(VPhoneBundleReport(bundle: a).template == template.identifier)
+ #expect(try VPhoneBundleReport(bundle: fixture.library.bundle(named: "own")).template == nil)
+ // A plain clone of a clone shares the template's blocks too.
+ let b = try VPhoneBundleOperations.clone(bundleNamed: "phone-a", to: "phone-b", in: fixture.library, newIdentity: true)
+ #expect(VPhoneMachineTemplates.readSource(inBundle: b.url)?.identifier == template.identifier)
+ #expect(VPhoneMachineTemplates.usage(in: fixture.library) == [template.identifier: ["phone-a", "phone-b"]])
+ // An export leaves it out: an import shares nothing.
+ #expect(VPhoneBundleOperations.exportExcludePatterns.contains { fnmatch($0, VPhoneMachineTemplates.sourceFileName, 0) == 0 })
+
+ // Deleting one of two: still used.
+ let sourceA = VPhoneMachineTemplates.readSource(inBundle: a.url)
+ try VPhoneBundleOperations.delete(bundleNamed: "phone-a", in: fixture.library)
+ #expect(VPhoneMachineTemplates.unusedTemplate(after: sourceA, in: fixture.library) == nil)
+ // Deleting the last: noticed, and the template is still there.
+ let sourceB = VPhoneMachineTemplates.readSource(inBundle: b.url)
+ try VPhoneBundleOperations.delete(bundleNamed: "phone-b", in: fixture.library)
+ let unused = try #require(VPhoneMachineTemplates.unusedTemplate(after: sourceB, in: fixture.library))
+ #expect(unused.identifier == template.identifier)
+ #expect(exists(template.url))
+ #expect(VPhoneMachineTemplates.allocatedBytes(of: template.url) > 0)
+ // A machine that was never cloned, or a template already deleted: nothing to say.
+ #expect(VPhoneMachineTemplates.unusedTemplate(after: nil, in: fixture.library) == nil)
+ try VPhoneMachineTemplates.delete(template.identifier, in: fixture.library)
+ #expect(VPhoneMachineTemplates.unusedTemplate(after: sourceB, in: fixture.library) == nil)
+ }
+
+ @Test func `an unreadable or foreign source record is ignored`() throws {
+ let fixture = try makeFixture()
+ defer { fixture.cleanUp() }
+ let machine = try makeMachine("m", in: fixture)
+ let file = machine.url.appendingPathComponent(VPhoneMachineTemplates.sourceFileName)
+ try Data("junk".utf8).write(to: file)
+ #expect(VPhoneMachineTemplates.readSource(inBundle: machine.url) == nil)
+ try VPhoneMachineTemplates.writeSource(VPhoneMachineTemplateSource(identifier: "../../etc"), inBundle: machine.url)
+ #expect(VPhoneMachineTemplates.readSource(inBundle: machine.url) == nil)
+ #expect(VPhoneMachineTemplates.usage(in: fixture.library).isEmpty)
+ }
}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/SystemTrimTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/SystemTrimTests.swift
new file mode 100644
index 00000000..bae3a2d7
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/SystemTrimTests.swift
@@ -0,0 +1,337 @@
+import Darwin
+import Foundation
+import Testing
+@testable import VPhoneCoreKit
+
+/// The offline trim of a template's System volume: the tier lists, the path
+/// rules, applying a trim to a folder laid out like the volume, and reading
+/// the disk layout from `hdiutil` and `diskutil` output.
+struct SystemTrimTests {
+ // MARK: - Lists
+
+ @Test func `each tier contains the one below it and none deletes nothing`() throws {
+ #expect(VPhoneSystemTrimSpec.none.entries.isEmpty)
+ let conservative = try VPhoneSystemTrimSpec(tier: .conservative).entries.map(\.path)
+ let standard = VPhoneSystemTrimSpec.standard.entries.map(\.path)
+ #expect(conservative == ["usr/standalone/update"])
+ #expect(Set(conservative).isSubset(of: Set(standard)))
+ #expect(standard.count == 4)
+ #expect(VPhoneSystemTrimTier.none < .conservative && .conservative < .standard && .standard < .aggressive)
+ }
+
+ @Test func `entries are relative, safe and do not overlap`() {
+ let entries = VPhoneSystemTrim.entries(keptLanguages: VPhoneSystemTrim.defaultKeptLanguages)
+ for entry in entries {
+ #expect(VPhoneSystemTrim.isSafeRelativePath(entry.path), "\(entry.path)")
+ #expect(!entry.path.hasPrefix("/"))
+ #expect(!entry.note.isEmpty)
+ }
+ for (i, a) in entries.enumerated() {
+ for b in entries[(i + 1)...] {
+ #expect(a.path != b.path)
+ #expect(!a.path.hasPrefix(b.path + "/"), "\(a.path) is inside \(b.path)")
+ #expect(!b.path.hasPrefix(a.path + "/"), "\(b.path) is inside \(a.path)")
+ }
+ }
+ // Never on any list: the dyld cache and its symbols, ML models, apps.
+ let all = entries.map(\.path).joined(separator: "\n")
+ for forbidden in ["dyld", "Cryptexes", "Applications", ".mlmodelc", "symbols"] {
+ #expect(!all.contains(forbidden), "\(forbidden)")
+ }
+ }
+
+ @Test func `path rules refuse anything that could leave the volume`() {
+ for good in ["a", "a/b", "System/Library/x.bundle"] {
+ #expect(VPhoneSystemTrim.isSafeRelativePath(good))
+ }
+ for bad in ["", "/a", "a/../b", "..", ".", "a//b", "a/", "a/./b", "a\u{0}b"] {
+ #expect(!VPhoneSystemTrim.isSafeRelativePath(bad), "\(bad)")
+ }
+ }
+
+ @Test func `aggressive is reserved and refused`() {
+ #expect(!VPhoneSystemTrimTier.aggressive.isSupported)
+ #expect(throws: VPhoneSystemTrimError.unsupportedTier("aggressive")) {
+ try VPhoneSystemTrimTier.parse("aggressive")
+ }
+ #expect(throws: VPhoneSystemTrimError.unsupportedTier("aggressive")) {
+ try VPhoneSystemTrimSpec(tier: .aggressive)
+ }
+ #expect(throws: VPhoneSystemTrimError.unknownTier("heavy")) {
+ try VPhoneSystemTrimTier.parse("heavy")
+ }
+ }
+
+ @Test func `kept languages default to en, zh-Hans and zh, and en is always kept`() throws {
+ #expect(VPhoneSystemTrimSpec.standard.keptLanguages == ["en", "zh", "zh-Hans"])
+ #expect(try VPhoneSystemTrimSpec(tier: .standard) == .standard)
+ #expect(try VPhoneSystemTrimSpec.parse(tier: "standard", keptLanguages: "ja, fr").keptLanguages == ["en", "fr", "ja"])
+ // A tier without language data keeps no list.
+ #expect(try VPhoneSystemTrimSpec(tier: .conservative).keptLanguages.isEmpty)
+ #expect(throws: VPhoneSystemTrimError.languagesUnused("conservative")) {
+ try VPhoneSystemTrimSpec.parse(tier: "conservative", keptLanguages: "en")
+ }
+ #expect(throws: VPhoneSystemTrimError.invalidLanguage("../x")) {
+ try VPhoneSystemTrimSpec.parse(tier: "standard", keptLanguages: "../x")
+ }
+ }
+
+ @Test func `the key value names tier, list version and kept languages, and reads back`() throws {
+ #expect(VPhoneSystemTrimSpec.none.keyValue == "none")
+ #expect(try VPhoneSystemTrimSpec(tier: .conservative).keyValue == "conservative/\(VPhoneSystemTrim.listVersion)")
+ #expect(VPhoneSystemTrimSpec.standard.keyValue == "standard/\(VPhoneSystemTrim.listVersion)/en,zh,zh-Hans")
+ for spec in try [VPhoneSystemTrimSpec.none, .standard, VPhoneSystemTrimSpec(tier: .conservative),
+ VPhoneSystemTrimSpec(tier: .standard, keptLanguages: ["ja"])]
+ {
+ #expect(try VPhoneSystemTrimSpec(keyValue: spec.keyValue) == spec)
+ }
+ #expect(throws: VPhoneSystemTrimError.unavailableListVersion(99)) {
+ try VPhoneSystemTrimSpec(keyValue: "standard/99/en")
+ }
+ #expect(throws: VPhoneSystemTrimError.self) { try VPhoneSystemTrimSpec(keyValue: "standard/1") }
+ #expect(throws: VPhoneSystemTrimError.self) { try VPhoneSystemTrimSpec(keyValue: "standard/1/zh,en") }
+ #expect(VPhoneSystemTrimSpec.tier(ofKeyValue: "standard/7/en") == .standard)
+ #expect(VPhoneSystemTrimSpec.tier(ofKeyValue: "none") == VPhoneSystemTrimTier.none)
+ #expect(VPhoneSystemTrimSpec.tier(ofKeyValue: "bogus") == nil)
+ }
+
+ @Test func `a trim permits only what its entries select`() throws {
+ let spec = VPhoneSystemTrimSpec.standard
+ #expect(spec.permits("usr/standalone/update/Mav24.Release.bbfw"))
+ #expect(spec.permits("System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets"))
+ #expect(spec.permits("System/Library/NanoTimeKit/FaceBundles/Kaleidoscope.bundle"))
+ #expect(spec.permits("System/Library/LinguisticData/RequiredAssets_ja.bundle"))
+
+ for kept in ["en", "zh-Hans", "zh"] {
+ #expect(!spec.permits("System/Library/LinguisticData/RequiredAssets_\(kept).bundle"), "\(kept)")
+ }
+ #expect(!spec.permits("System/Library/LinguisticData/ja"))
+ #expect(!spec.permits("System/Library/LinguisticData/Info.plist"))
+ #expect(!spec.permits("usr/standalone/update")) // the folder itself stays
+ #expect(!spec.permits("usr/standalone/update/ramdisk/arm64eSURamDisk.dmg")) // only direct children
+ #expect(!spec.permits("usr/standalone/update/.."))
+ #expect(!spec.permits("usr/standalone/update/../../../etc"))
+ #expect(!spec.permits("/usr/standalone/update/x"))
+ #expect(!spec.permits("System/Library/Caches/com.apple.dyld"))
+ // Conservative stops at its own entry.
+ #expect(try !VPhoneSystemTrimSpec(tier: .conservative).permits("System/Library/NanoTimeKit/FaceBundles/x"))
+ #expect(!VPhoneSystemTrimSpec.none.permits("usr/standalone/update/x"))
+ }
+
+ @Test func `a recorded trim can only be repeated or widened from conservative`() throws {
+ let conservative = try VPhoneSystemTrimSpec(tier: .conservative)
+ let standard = VPhoneSystemTrimSpec.standard
+ let japanese = try VPhoneSystemTrimSpec(tier: .standard, keptLanguages: ["ja"])
+ #expect(standard.canFollow(recorded: "none"))
+ #expect(standard.canFollow(recorded: standard.keyValue))
+ #expect(standard.canFollow(recorded: conservative.keyValue))
+ #expect(!conservative.canFollow(recorded: standard.keyValue))
+ #expect(!VPhoneSystemTrimSpec.none.canFollow(recorded: conservative.keyValue))
+ #expect(!japanese.canFollow(recorded: standard.keyValue))
+ #expect(!standard.canFollow(recorded: "garbage"))
+ }
+
+ @Test func `a create naming another trim than the template has conflicts`() throws {
+ let slimmed = VPhoneTemplateSlimmingRequest.defaultSlimming
+ let key = MachineTemplateKeyTests.key(slimming: slimmed)
+ #expect(slimmed.trimTier == VPhoneSystemTrimSpec.standard.keyValue)
+ #expect(VPhoneMachineTemplateRequest(slimming: slimmed).conflicts(with: key).isEmpty)
+ let untrimmed = try VPhoneTemplateSlimmingRequest(trimTier: "none").resolve()
+ #expect(VPhoneMachineTemplateRequest(slimming: untrimmed).conflicts(with: key).count == 1)
+ #expect(VPhoneMachineTemplateRequest().conflicts(with: key).isEmpty)
+ }
+
+ // MARK: - Applying
+
+ private struct Volume {
+ let root: URL
+ let outside: URL
+
+ func cleanUp() {
+ try? FileManager.default.removeItem(at: root.deletingLastPathComponent())
+ }
+
+ func exists(_ relative: String) -> Bool {
+ var info = stat()
+ return lstat(root.appendingPathComponent(relative).path, &info) == 0
+ }
+ }
+
+ /// A folder laid out like the parts of a System volume the lists name,
+ /// with a sibling folder outside it that must survive everything.
+ private func makeVolume(system: Bool = true) throws -> Volume {
+ let fm = FileManager.default
+ let base = fm.temporaryDirectory.appendingPathComponent("trim-\(UUID().uuidString)")
+ let root = base.appendingPathComponent("system")
+ let outside = base.appendingPathComponent("outside")
+ try fm.createDirectory(at: outside, withIntermediateDirectories: true)
+ try Data(repeating: 7, count: 40000).write(to: outside.appendingPathComponent("precious"))
+ func file(_ relative: String, _ size: Int = 20000) throws {
+ let url = root.appendingPathComponent(relative)
+ try fm.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+ try Data(repeating: 1, count: size).write(to: url)
+ }
+ if system {
+ try file(VPhoneSystemTrim.systemVolumeMarker, 100)
+ }
+ try file("usr/standalone/update/Mav24.Release.bbfw")
+ try file("usr/standalone/update/ramdisk/arm64eSURamDisk.dmg")
+ try file("usr/standalone/firmware/keep.bin")
+ try file("System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets/a.asset/x")
+ try file("System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_ContextKit/keep")
+ try file("System/Library/NanoTimeKit/FaceBundles/Kaleidoscope.bundle/Info.plist")
+ for language in ["en", "zh-Hans", "zh", "ja", "fr"] {
+ try file("System/Library/LinguisticData/RequiredAssets_\(language).bundle/data")
+ }
+ try file("System/Library/LinguisticData/ja/lexicon")
+ try file("System/Library/LinguisticData/Info.plist", 10)
+ // A link in a trimmed folder points out of the volume: it goes as a
+ // link, and what it points at stays.
+ try fm.createSymbolicLink(at: root.appendingPathComponent("usr/standalone/update/escape"), withDestinationURL: outside)
+ return Volume(root: root, outside: outside)
+ }
+
+ @Test func `standard deletes its entries, keeps everything else, and never follows a link out`() throws {
+ let volume = try makeVolume()
+ defer { volume.cleanUp() }
+ let root = try VPhoneConfinedDirectory(root: volume.root.path)
+ var lines: [String] = []
+
+ let result = try VPhoneSystemTrimSpec.standard.apply(to: root) { lines.append($0) }
+
+ #expect(result.trim == VPhoneSystemTrimSpec.standard.keyValue)
+ #expect(result.entries.map(\.path) == VPhoneSystemTrimSpec.standard.entries.map(\.path))
+ #expect(result.entries.allSatisfy { !$0.absent })
+ #expect(result.entries[0].removed == ["Mav24.Release.bbfw", "escape", "ramdisk"])
+ #expect(result.entries[3].removed == ["RequiredAssets_fr.bundle", "RequiredAssets_ja.bundle"])
+ #expect(result.bytes >= 6 * 20000)
+ #expect(lines.count == 4)
+
+ #expect(volume.exists("usr/standalone/update"))
+ #expect(!volume.exists("usr/standalone/update/Mav24.Release.bbfw"))
+ #expect(!volume.exists("usr/standalone/update/escape"))
+ #expect(volume.exists("usr/standalone/firmware/keep.bin"))
+ #expect(!volume.exists("System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets"))
+ #expect(volume.exists("System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_ContextKit/keep"))
+ #expect(volume.exists("System/Library/NanoTimeKit/FaceBundles"))
+ #expect(!volume.exists("System/Library/NanoTimeKit/FaceBundles/Kaleidoscope.bundle"))
+ for language in ["en", "zh-Hans", "zh"] {
+ #expect(volume.exists("System/Library/LinguisticData/RequiredAssets_\(language).bundle"))
+ }
+ #expect(!volume.exists("System/Library/LinguisticData/RequiredAssets_ja.bundle"))
+ #expect(volume.exists("System/Library/LinguisticData/ja/lexicon"))
+ #expect(volume.exists("System/Library/LinguisticData/Info.plist"))
+ #expect(FileManager.default.fileExists(atPath: volume.outside.appendingPathComponent("precious").path))
+
+ // Again: nothing left to delete, nothing absent either.
+ let again = try VPhoneSystemTrimSpec.standard.apply(to: root)
+ #expect(again.bytes == 0)
+ #expect(again.entries.allSatisfy { $0.removed.isEmpty })
+ }
+
+ @Test func `conservative stops at usr standalone update`() throws {
+ let volume = try makeVolume()
+ defer { volume.cleanUp() }
+ let result = try VPhoneSystemTrimSpec(tier: .conservative).apply(to: VPhoneConfinedDirectory(root: volume.root.path))
+ #expect(result.entries.map(\.path) == ["usr/standalone/update"])
+ #expect(volume.exists("System/Library/NanoTimeKit/FaceBundles/Kaleidoscope.bundle"))
+ #expect(volume.exists("System/Library/LinguisticData/RequiredAssets_ja.bundle"))
+ }
+
+ @Test func `a listed folder that is a link is refused, not followed`() throws {
+ let volume = try makeVolume()
+ defer { volume.cleanUp() }
+ let faces = volume.root.appendingPathComponent("System/Library/NanoTimeKit/FaceBundles")
+ try FileManager.default.removeItem(at: faces)
+ try FileManager.default.createSymbolicLink(at: faces, withDestinationURL: volume.outside)
+
+ #expect(throws: VPhoneConfinedDirectoryError.self) {
+ try VPhoneSystemTrimSpec.standard.apply(to: VPhoneConfinedDirectory(root: volume.root.path))
+ }
+ #expect(FileManager.default.fileExists(atPath: volume.outside.appendingPathComponent("precious").path))
+ }
+
+ @Test func `missing entries are reported absent`() throws {
+ let volume = try makeVolume()
+ defer { volume.cleanUp() }
+ try FileManager.default.removeItem(at: volume.root.appendingPathComponent("System/Library/NanoTimeKit"))
+ try FileManager.default.removeItem(at: volume.root.appendingPathComponent(
+ "System/Library/PreinstalledAssetsV2/RequiredByOs/com_apple_MobileAsset_SharingDeviceAssets",
+ ))
+ let result = try VPhoneSystemTrimSpec.standard.apply(to: VPhoneConfinedDirectory(root: volume.root.path))
+ #expect(result.entries.map(\.absent) == [false, true, true, false])
+ }
+
+ @Test func `a volume without the iOS marker is refused before anything is deleted`() throws {
+ let volume = try makeVolume(system: false)
+ defer { volume.cleanUp() }
+ #expect(throws: VPhoneSystemTrimError.notSystemVolume) {
+ try VPhoneSystemTrimSpec.standard.apply(to: VPhoneConfinedDirectory(root: volume.root.path))
+ }
+ #expect(volume.exists("usr/standalone/update/Mav24.Release.bbfw"))
+ }
+
+ @Test func `removal reports allocated bytes and counts a second hard link as nothing`() throws {
+ let fm = FileManager.default
+ let base = fm.temporaryDirectory.appendingPathComponent("rm-\(UUID().uuidString)")
+ defer { try? fm.removeItem(at: base) }
+ try fm.createDirectory(at: base.appendingPathComponent("d"), withIntermediateDirectories: true)
+ try Data(repeating: 1, count: 100_000).write(to: base.appendingPathComponent("d/a"))
+ try Data(repeating: 2, count: 100_000).write(to: base.appendingPathComponent("b"))
+ try fm.linkItem(at: base.appendingPathComponent("b"), to: base.appendingPathComponent("d/b-link"))
+ let root = try VPhoneConfinedDirectory(root: base.path)
+
+ let removed = try root.removeItem("d")
+ #expect(removed >= 100_000 && removed < 200_000)
+ #expect(try root.removeItem("missing") == 0)
+ }
+
+ // MARK: - Disk layout
+
+ @Test func `the attached disk and its APFS store come from hdiutil output`() {
+ let output = """
+ /dev/disk6 \tGUID_partition_scheme \t
+ /dev/disk6s1 \tApple_APFS \t
+ /dev/disk7 \tEF57347C-0000-11AA-AA11-0030654\t
+ /dev/disk7s1 \t41504653-0000-11AA-AA11-0030654\t
+ """
+ let disks = VPhoneGuestDiskLayout.attachedDisks(fromAttachOutput: output)
+ #expect(disks.wholeDisk == "disk6")
+ #expect(disks.store == "disk6s1")
+ #expect(VPhoneGuestDiskLayout.attachedDisks(fromAttachOutput: "").wholeDisk == nil)
+ #expect(VPhoneGuestDiskLayout.isDeviceName("disk12s3"))
+ #expect(!VPhoneGuestDiskLayout.isDeviceName("/dev/disk1"))
+ #expect(!VPhoneGuestDiskLayout.isDeviceName("disk1;rm"))
+ }
+
+ private func apfsList(container: String = "disk7", store: String = "disk6s1", systemRoles: [[String]]) throws -> Data {
+ let volumes: [[String: Any]] = systemRoles.enumerated().map { index, roles in
+ ["DeviceIdentifier": "\(container)s\(index + 1)", "Roles": roles, "Name": "v\(index)"]
+ }
+ let plist: [String: Any] = ["Containers": [[
+ "ContainerReference": container,
+ "PhysicalStores": [["DeviceIdentifier": store]],
+ "Volumes": volumes,
+ ]]]
+ return try PropertyListSerialization.data(fromPropertyList: plist, format: .xml, options: 0)
+ }
+
+ @Test func `the System volume is found by role, on the attached store only`() throws {
+ let data = try apfsList(systemRoles: [["Data"], ["Preboot"], ["System"], ["xART"]])
+ #expect(try VPhoneGuestDiskLayout.systemVolume(fromAPFSList: data, container: "disk7", physicalStore: "disk6s1") == "disk7s3")
+ #expect(throws: VPhoneSystemTrimError.self) {
+ try VPhoneGuestDiskLayout.systemVolume(fromAPFSList: data, container: "disk7", physicalStore: "disk9s1")
+ }
+ #expect(throws: VPhoneSystemTrimError.self) {
+ try VPhoneGuestDiskLayout.systemVolume(fromAPFSList: data, container: "disk8", physicalStore: "disk6s1")
+ }
+ let none = try apfsList(systemRoles: [["Data"]])
+ #expect(throws: VPhoneSystemTrimError.self) {
+ try VPhoneGuestDiskLayout.systemVolume(fromAPFSList: none, container: "disk7", physicalStore: "disk6s1")
+ }
+ let two = try apfsList(systemRoles: [["System"], ["System"]])
+ #expect(throws: VPhoneSystemTrimError.self) {
+ try VPhoneGuestDiskLayout.systemVolume(fromAPFSList: two, container: "disk7", physicalStore: "disk6s1")
+ }
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
index 2cf20de7..784fcd3f 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSetupBootTests.swift
@@ -250,7 +250,11 @@ struct TemplateSetupBootTests {
#expect(guest.pinnedName == nil)
#expect(Set(outcome.durations.keys) == Set(VPhoneTemplateSetupStep.allCases))
- let steps = outcome.applying(to: VPhoneMachineTemplateSteps())
+ // The offline trim records its tier before the setup boot, which
+ // leaves it alone.
+ let trimmed = VPhoneMachineTemplateSteps(trimTier: VPhoneTemplateSlimmingRequest.defaultTrimTier)
+ let steps = outcome.applying(to: trimmed)
+ #expect(steps.trimTier == trimmed.trimTier)
#expect(steps.setupDone)
#expect(steps.snapshotDeleted)
#expect(steps.slimming == VPhoneTemplateSlimmingRequest.defaultSlimming)
@@ -274,7 +278,7 @@ struct TemplateSetupBootTests {
let slimming = try VPhoneTemplateSlimmingRequest(accountsOff: true).resolve()
let outcome = try run(guest, slimming: slimming).get()
#expect(guest.groups.contains("accounts"))
- #expect(outcome.applying(to: VPhoneMachineTemplateSteps()).slimming == slimming)
+ #expect(outcome.applying(to: VPhoneMachineTemplateSteps(trimTier: slimming.trimTier)).slimming == slimming)
}
@Test func `a busy snapshot deletion is retried`() throws {
@@ -470,6 +474,12 @@ struct TemplateSetupRecordingTests {
}
// Before the setup boot the key's promise is not kept.
#expect(throws: VPhoneMachineTemplateError.self) { try VPhoneMachineTemplates.freeze(build) }
+ // The default trim runs first and records its tier; its snapshot is
+ // still there, so the build still does not freeze.
+ try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) {
+ $0.trimTier = VPhoneTemplateSlimmingRequest.defaultTrimTier
+ }
+ #expect(throws: VPhoneMachineTemplateError.self) { try VPhoneMachineTemplates.freeze(build) }
try VPhoneMachineTemplates.recordSetupBoot(outcome(complete: true), inBundle: build.bundleURL)
let record = try #require(try VPhoneMachineTemplates.readRecord(inBundle: build.bundleURL))
@@ -477,7 +487,7 @@ struct TemplateSetupRecordingTests {
#expect(record.steps.snapshotDeleted)
#expect(record.steps.serviceProfile == "trimmed")
#expect(record.steps.removedApps.count == 10)
- #expect(record.steps.trimTier == "none")
+ #expect(record.steps.trimTier == VPhoneTemplateSlimmingRequest.defaultTrimTier)
let template = try VPhoneMachineTemplates.freeze(build)
#expect(template.record.frozen)
@@ -503,15 +513,15 @@ struct TemplateSetupRecordingTests {
@Test func `a file trim recorded before the setup boot survives it`() throws {
var slimming = VPhoneTemplateSlimmingRequest.defaultSlimming
- slimming.trimTier = "standard"
+ slimming.trimTier = "conservative/1"
let (root, build, lock) = try makeBuild(slimming: slimming)
defer {
lock.release()
try? FileManager.default.removeItem(at: root)
}
- try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) { $0.trimTier = "standard" }
+ try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) { $0.trimTier = "conservative/1" }
try VPhoneMachineTemplates.recordSetupBoot(outcome(complete: true), inBundle: build.bundleURL)
- #expect(try VPhoneMachineTemplates.freeze(build).record.steps.trimTier == "standard")
+ #expect(try VPhoneMachineTemplates.freeze(build).record.steps.trimTier == "conservative/1")
}
}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSlimmingRequestTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSlimmingRequestTests.swift
index bed641d6..faa6de23 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSlimmingRequestTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/TemplateSlimmingRequestTests.swift
@@ -44,6 +44,30 @@ struct TemplateSlimmingRequestTests {
}
}
+ @Test func `the trim defaults to standard and is stored as its key value`() throws {
+ #expect(Request.defaultTrimTier == VPhoneSystemTrimSpec.standard.keyValue)
+ #expect(Request.defaultTrimTier == "standard/1/en,zh,zh-Hans")
+ #expect(try Request(trimTier: "conservative").resolve().trimTier == "conservative/1")
+ #expect(try Request(trimTier: "none").resolve().trimTier == "none")
+ // --keep-languages alone means the standard tier keeping them.
+ let japanese = try Request(keepLanguages: "ja").resolve()
+ #expect(japanese.trimTier == "standard/1/en,ja")
+ #expect(japanese.setupBoot)
+ #expect(!Request(keepLanguages: "ja").isEmpty)
+ #expect(Request.trimTiers == ["none", "conservative", "standard"])
+ }
+
+ @Test func `trim switches that cannot apply are refused`() {
+ for request in [
+ Request(trimTier: "aggressive"),
+ Request(trimTier: "conservative", keepLanguages: "ja"),
+ Request(trimTier: "standard", keepLanguages: "../x"),
+ Request(slim: false, keepLanguages: "ja"),
+ ] {
+ #expect(throws: VPhoneTemplateSlimmingError.self, "\(request)") { try request.resolve() }
+ }
+ }
+
@Test func `parts can be turned off on their own`() throws {
let noProfile = try Request(serviceProfile: "none").resolve()
#expect(noProfile.serviceProfile == "none")
@@ -100,6 +124,8 @@ struct TemplateSlimmingRequestTests {
Request(removeApps: false),
Request(keepApps: ["com.apple.games"]),
Request(accountsOff: true),
+ Request(trimTier: "conservative"),
+ Request(keepLanguages: "ja"),
]
let identifiers = try Set(requests.map { try MachineTemplateKeyTests.key(slimming: $0.resolve()).identifier })
#expect(identifiers.count == requests.count)