From 13d5ddb4a4d79c0d7babfb24c23436834c1981d2 Mon Sep 17 00:00:00 2001 From: William Theaker Date: Mon, 13 May 2024 12:44:26 -0400 Subject: [PATCH] Minor documentation improvements. (#819) * Minor documentation improvements. * Fix MD031 * Add sudo to mount instructions. --- Sources/tart/Commands/Clone.swift | 2 +- Sources/tart/Commands/Create.swift | 2 +- Sources/tart/Commands/List.swift | 2 +- Sources/tart/Commands/Rename.swift | 4 ++-- docs/integrations/vm-management.md | 17 +++++++++-------- docs/quick-start.md | 8 ++++---- 6 files changed, 18 insertions(+), 17 deletions(-) diff --git a/Sources/tart/Commands/Clone.swift b/Sources/tart/Commands/Clone.swift index ab72d8c..57dedff 100644 --- a/Sources/tart/Commands/Clone.swift +++ b/Sources/tart/Commands/Clone.swift @@ -8,7 +8,7 @@ struct Clone: AsyncParsableCommand { discussion: """ Creates a local virtual machine by cloning either a remote or another local virtual machine. - Due to copy-on-write magic in Apple File System a cloned VM won't actually claim all the space right away. + Due to copy-on-write magic in Apple File System, a cloned VM won't actually claim all the space right away. Only changes to a cloned disk will be written and claim new space. By default, Tart checks available capacity in Tart's home directory and checks if there is enough space for the worst possible scenario: when the whole disk will be modified. diff --git a/Sources/tart/Commands/Create.swift b/Sources/tart/Commands/Create.swift index b816fc2..1abdd1d 100644 --- a/Sources/tart/Commands/Create.swift +++ b/Sources/tart/Commands/Create.swift @@ -16,7 +16,7 @@ struct Create: AsyncParsableCommand { @Flag(help: "create a Linux VM") var linux: Bool = false - @Option(help: ArgumentHelp("Disk size in Gb")) + @Option(help: ArgumentHelp("Disk size in GB")) var diskSize: UInt16 = 50 func validate() throws { diff --git a/Sources/tart/Commands/List.swift b/Sources/tart/Commands/List.swift index c958007..2234597 100644 --- a/Sources/tart/Commands/List.swift +++ b/Sources/tart/Commands/List.swift @@ -44,7 +44,7 @@ struct List: AsyncParsableCommand { if source == nil || source == "oci" { infos += sortedInfos(try VMStorageOCI().list().map { (name, vmDir, _) in - try VMInfo(Source: "oci", Name: name, Disk: vmDir.sizeGB(), Size: vmDir.allocatedSizeGB(), Running: vmDir.running(), State: vmDir.state().rawValue) + try VMInfo(Source: "OCI", Name: name, Disk: vmDir.sizeGB(), Size: vmDir.allocatedSizeGB(), Running: vmDir.running(), State: vmDir.state().rawValue) }) } diff --git a/Sources/tart/Commands/Rename.swift b/Sources/tart/Commands/Rename.swift index 70ae351..66ad9bd 100644 --- a/Sources/tart/Commands/Rename.swift +++ b/Sources/tart/Commands/Rename.swift @@ -2,7 +2,7 @@ import ArgumentParser import Foundation struct Rename: AsyncParsableCommand { - static var configuration = CommandConfiguration(abstract: "Rename a VM") + static var configuration = CommandConfiguration(abstract: "Rename a local VM") @Argument(help: "VM name", completion: .custom(completeLocalMachines)) var name: String @@ -20,7 +20,7 @@ struct Rename: AsyncParsableCommand { let localStorage = VMStorageLocal() if !localStorage.exists(name) { - throw ValidationError("failed to rename a non-existent VM: \(name)") + throw ValidationError("failed to rename a non-existent local VM: \(name)") } if localStorage.exists(newName) { diff --git a/docs/integrations/vm-management.md b/docs/integrations/vm-management.md index fcd2991..cc459b4 100644 --- a/docs/integrations/vm-management.md +++ b/docs/integrations/vm-management.md @@ -15,7 +15,7 @@ tart create --from-ipsw=latest sonoma-vanilla tart run sonoma-vanilla ``` -After the initial booting of the VM you'll need to manually go through the macOS installation process. As a convention we recommend creating an `admin` user with an `admin` password. After the regular installation please do some additional modifications in the VM: +After the initial booting of the VM, you'll need to manually go through the macOS installation process. As a convention we recommend creating an `admin` user with an `admin` password. After the regular installation please do some additional modifications in the VM: 1. Enable Auto-Login. Users & Groups -> Login Options -> Automatic login -> admin. 2. Allow SSH. Sharing -> Remote Login @@ -48,7 +48,7 @@ sudo ufw allow ssh ## Configuring a VM -By default, a tart VM uses 2 CPUs and 4 GB of memory with a `1024x768` display. This can be changed with `tart set` command. +By default, a Tart VM uses 2 CPUs and 4 GB of memory with a `1024x768` display. This can be changed after VM creation with `tart set` command. Please refer to `tart set --help` for additional details. ## Building with Packer @@ -92,18 +92,19 @@ Here is a [repository with Packer templates](https://github.com/cirruslabs/macos ## Working with a Remote OCI Container Registry - -For example, let's say you want to push/pull images to a registry hosted at https://acme.io/. - +Tart supports interacting with Open Container Initiative (OCI) registries, but only runs images created and pushed by Tart. This means images created for container engines, like Docker, can't be pulled. Instead, create a custom image as documented above. + +For example, let's say you want to push/pull images to an OCI registry hosted at `https://acme.io/`. ### Registry Authorization -First, you need to log in and save credential for `acme.io` host via `tart login` command: +First, you need to login to `acme.io` with the `tart login` command: ```bash tart login acme.io ``` +If you login to your registry with OAuth, you may need to create an access token to use as the password. Credentials are securely stored in Keychain. In addition, Tart supports [Docker credential helpers](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers) @@ -128,10 +129,10 @@ You can either pull an image: tart pull acme.io/remoteorg/name:latest ``` -...or instantiate a VM from a remote image: +or create a VM from a remote image: ```bash tart clone acme.io/remoteorg/name:latest my-local-vm-name ``` -This invocation calls the `tart pull` implicitly (if the image is not being present) before doing the actual cloning. +If the specified image is not already present, this invocation calls the `tart pull` implicitly before cloning. diff --git a/docs/quick-start.md b/docs/quick-start.md index caf4f26..40f854a 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -13,7 +13,7 @@ tart run sonoma-base ??? info "Manual installation from a release archive" It's also possible to manually install `tart` binary from the latest released archive: - + ```bash curl -LO https://github.com/cirruslabs/tart/releases/latest/download/tart-arm64.tar.gz tar -xzvf tart-arm64.tar.gz @@ -129,7 +129,7 @@ Note: to use the directory mounting feature, the guest VM needs to run macOS 13. ??? tip "Changing mount location" It is possible to remount the directories after a virtual machine is started by running the following commands: - + ```bash sudo umount "/Volumes/My Shared Files" mkdir ~/workspace @@ -143,8 +143,8 @@ Note: to use the directory mounting feature, the guest VM needs to run macOS 13. To be able to access the shared directories from the Linux guest, you need to manually mount the virtual filesystem first: ```bash -mkdir /mnt/shared -mount -t virtiofs com.apple.virtio-fs.automount /mnt/shared +sudo mkdir /mnt/shared +sudo mount -t virtiofs com.apple.virtio-fs.automount /mnt/shared ``` The directory we've mounted above will be accessible from the `/mnt/shared/project` path inside a guest VM.