|
| 1 | +## Introduction |
| 2 | +So, what is AutoPilot? Are we talking about an Airbus A320? Nope, just some random GitHub project on the internet. Regardless, here's the rundown. |
| 3 | + |
| 4 | +AutoPilot is a script developed by me - Coopydood - to automate the creation of an executable QEMU script file. However, it doesn't just automate it, it also **personalises it based on your preferences.** |
| 5 | + |
| 6 | +The way it works is by asking you - the user - a series of questions about your preferences for the virtual machine. This includes things like the virtual CPU cores, allocated RAM, target OS, etc. Then, AutoPilot uses this information to generate a fully-customised script file, derived from a pre-made base script - with all your preferences. |
| 7 | + |
| 8 | +The generated script file is **immediately valid** and can be run instantly after AutoPilot completes - which in most cases is under 3 minutes - depending on what you choose to customise. This makes it super easy to get a basic macOS VM up and running with zero user tinkering, all while catering to personal preferences. |
| 9 | + |
| 10 | +With the intro out of the way, I'll now go into more detail about each AutoPilot stage, including acceptable values and how to enter them. |
| 11 | +*** |
| 12 | +NOTE: Any "Accepted" values with a **bold** suffix indicate that you must include it when inputting your custom value into AutoPilot, such as file extensions. |
| 13 | + |
| 14 | +*** |
| 15 | +## 1. Name your config file |
| 16 | +This really is as simple as it sounds. You can choose what you want the file name of the config script to be. This can be an **alphanumeric string** with no special characters except `_` and `-`. |
| 17 | + |
| 18 | +| **Default** | Accepted | _Examples_ | |
| 19 | +|:-----------:|:---------------:|:--------------------------------------------:| |
| 20 | +| boot.sh | [string]**.sh** | macOS.sh<br>macOS-1015.sh<br>ultimate_kvm.sh | |
| 21 | + |
| 22 | +*** |
| 23 | +## 2. Set target OS |
| 24 | +This setting only really has one definitive use right now - virtual network adapter model auto selection. Other than that, it is purely cosmetic at this time. It's still recommended to set this value properly in case future functionality and features depend on it. |
| 25 | + |
| 26 | +If defining a custom value, only a **4-digit value for macOS 10.XX releases**, or a **2-digit value for macOS 11 or later** is accepted. |
| 27 | +Do NOT include any subversions (i.e. 10.13.6, 10.15.7, etc.). |
| 28 | + |
| 29 | +In project versions v0.8.6 and later, this value is also now used to add a boot entry to the main menu for easy access. Again, this is purely cosmetic but something to consider. |
| 30 | + |
| 31 | +| **Default** | Accepted | _Examples_ | |
| 32 | +|:-----------:|:-----------------:|:------------:| |
| 33 | +| 1015 | 10XX<br>_(10.XX)_ | 1013<br>1014 | |
| 34 | +| | XX<br>_(>=11)_ | 11<br>12 | |
| 35 | + |
| 36 | +*** |
| 37 | +## 3. Set number of CPU cores |
| 38 | +Like any other virtual machine, the guest needs virtual cores to work with. As a general rule, use no more than **80%** of your _host's_ total cores. For example, if your host has _10 cores_, you shouldn't use any more than __8 virtual cores__. That's all I can recommend here - use your own judgment and scale to your hardware appropriately. |
| 39 | + |
| 40 | +| **Default** | Accepted | _Examples_ | |
| 41 | +|:-----------:|:--------:|:-----------:| |
| 42 | +| 2 | [number] | 4<br>6<br>8 | |
| 43 | + |
| 44 | +*** |
| 45 | +## 4. Set number of CPU threads |
| 46 | +Similar to the previous step, your guest needs **virtual threads** to work with. |
| 47 | + |
| 48 | +**THIS VALUE IS A MULTIPLIER.** This is calculated as **_virtual cores_ ✕ _virtual threads_**. |
| 49 | + |
| 50 | +For example, if you wanted a total of 4 virtual cores and 8 virtual threads, you would input 2 here. (4 ✕ [_**2**_] = 8) |
| 51 | + |
| 52 | +If this confuses you - and I don't blame you, I've confused myself - then leave this value as it is. |
| 53 | + |
| 54 | +| **Default** | Accepted | _Examples_ | |
| 55 | +|:-----------:|:--------:|:----------:| |
| 56 | +| 2 | [number] | 1<br>2 | |
| 57 | + |
| 58 | +*** |
| 59 | +## 5. Set CPU model |
| 60 | +This sets the model of the virtual CPU, and subsequently what the guest OS recognizes it as. |
| 61 | + |
| 62 | +**THIS SHOULD NOT BE CHANGED UNLESS YOU KNOW WHAT IT MEANS!** Refer to the [official QEMU documentation on CPU models](https://qemu-project.gitlab.io/qemu/system/qemu-cpu-models.html) for a comprehensive list of acceptable values. |
| 63 | + |
| 64 | +If you _**know**_ your **host** CPU model is supported natively by macOS (i.e. Intel Core i3, i5, i7, i9) or at least a **similar variant of a supported model** (such as the i9-10900K being similar to Apple's i9-10910), you can expose the real model to the guest using the `host` value. It might do something. Use at your own risk. |
| 65 | + |
| 66 | +| **Default** | Accepted | _Examples_ | |
| 67 | +|:-----------:|:-----------:|:--------------------:| |
| 68 | +| Penryn | [cpu_model] | Broadwell<br>IvyLake | |
| 69 | +| | host | | |
| 70 | + |
| 71 | +*** |
| 72 | +## 6. Set CPU feature arguments |
| 73 | +This lets you change the feature set of the virtual CPU. If you're a nerdy nerd nerd who nerds then you might find benefit in tinkering with this, but otherwise: |
| 74 | + |
| 75 | +**Don't change this unless you know what you're doing.** |
| 76 | + |
| 77 | +| **Default** | Accepted | _Examples_ | |
| 78 | +|:-------------------------------------------------------:|:-------------------:|:----------------:| |
| 79 | +| +ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check | +[arg] | +kvm | |
| 80 | +| | +[arg1],+[arg2] ... | +avx,+kvm,+ssse3 | |
| 81 | + |
| 82 | +*** |
| 83 | +## 7. Set amount of allocated RAM |
| 84 | +This one is very similar to the virtual CPU cores option in that it should be scaled relative to your host's hardware. macOS is surprisingly lenient when it comes to lesser RAM amounts, so you don't need to overdo it. |
| 85 | + |
| 86 | +My only recommendation would be: [_total host RAM_] − [_host idle RAM usage_] − 1GB >= **total virtual RAM** |
| 87 | + |
| 88 | +Example: If your host has 16GB total RAM, your host uses 4GB of RAM when idle, don't use any more than 11GB of RAM for the virtual machine. ([_16GB_] − [_4GB_] − 1GB = 11GB) |
| 89 | + |
| 90 | +| **Default** | Accepted | _Examples_ | |
| 91 | +|:-----------:|:-------------:|:---------------:| |
| 92 | +| 4G | [number]**G** | 2G<br>8G<br>16G | |
| 93 | + |
| 94 | +*** |
| 95 | +## 8. Set hard disk capacity |
| 96 | +You should think carefully about this one as it might be hard to change later. This is the capacity of your primary virtual hard drive that will be used for your macOS installation. Keep in mind **macOS uses upwards of 40GB for the system**, so you should base your total on how much you think you'll need. |
| 97 | + |
| 98 | +If you're just testing the project, you can leave it as is. If you plan on using the virtual machine long-term, perhaps make it a bit bigger to give yourself room. |
| 99 | + |
| 100 | +**NOTE: This is a dynamically-growing disk. The virtual hard disk file will grow as you use it. The full capacity is NOT used on the host's storage upon creation. If you've ever used VMware's virtual disks, it's the same as that.** Please also note that the _actual_ virtual capacity of the hard disk may be slightly larger than the value you specify. |
| 101 | + |
| 102 | +| **Default** | Accepted | _Examples_ | |
| 103 | +|:-----------:|:-------------:|:-------------------:| |
| 104 | +| 80G | [number]**G** | 60G<br>120G<br>256G | |
| 105 | + |
| 106 | +*** |
| 107 | +## 9. Set network adapter model |
| 108 | +This one is a bit more picky. macOS has a limited number of network drivers due to the limited hardware configurations that natively run macOS, therefore you need to pick a model with driver support. |
| 109 | + |
| 110 | +**Based on your target OS you chose earlier, the default option will auto-select the best model for your macOS version.** |
| 111 | + |
| 112 | +You can still override this if you'd like, but for most people, whatever is auto-selected will be fine. |
| 113 | + |
| 114 | +| **Default** | Accepted | _Examples_ | |
| 115 | +|:-------------:|:---------------:|:-----------------:| |
| 116 | +| e1000-82545em | [adapter_model] | e1000m<br>vmxnet3 | |
| 117 | +| vmxnet3 | | | |
| 118 | + |
| 119 | +*** |
| 120 | +## 10. Network MAC address |
| 121 | +The virtual network adapter needs a virtual MAC address to identify it. |
| 122 | + |
| 123 | +**The default is fine unless you intend on using features such as iMessage and FaceTime, as these services require specific MAC address values.** |
| 124 | + |
| 125 | +In this case, you should use your own custom one, or you can even have the script generate a random compatible one for you. I'd recommend the latter to make it more unique, at the risk of being perhaps a bit less reliable. |
| 126 | + |
| 127 | +| **Default** | Accepted | _Examples_ | |
| 128 | +|:-----------------:|:-------------------------------------:|:-----------------------------------------------------------:| |
| 129 | +| 00:16:cb:00:21:09 | XX:XX:XX:XX:XX:XX | 00:16:cb:00:48:02<br>00:16:ca:00:27:09<br>00:16:cr:00:87:33 | |
| 130 | + |
| 131 | +*** |
| 132 | +## 11. macOS Recovery image file |
| 133 | +To install macOS, you'll need an image of the macOS Recovery. |
| 134 | + |
| 135 | +The script can automatically download a recovery image of a macOS version of your choosing, or you can use one you already have. If you are using a custom image, it should be in the ***.img** format. You can drag a file onto the terminal window, or place a file called `BaseSystem.img` in the root of the project directory to have it be detected automatically. If it is in the ***.dmg** format - this is okay - the script will automatically detect this and convert it for you during the configuration process. |
| 136 | + |
| 137 | +You can also choose to skip this step, but this is not recommended. |
| 138 | + |
| 139 | +| **Default** | Accepted | _Examples_ | |
| 140 | +|:--------------:|:---------------:|:-----------------------------------:| |
| 141 | +| BaseSystem.img | [file_name].img | BaseSystem.img<br>macOSRecovery.img | |
| 142 | +| | [file_name].dmg | BaseSystem.dmg<br>InstallESD.dmg | |
| 143 | + |
| 144 | +*** |
| 145 | +## 12. Screen resolution |
| 146 | +As of [v0.9.2](https://github.com/Coopydood/ultimate-macOS-KVM/releases/tag/v0.9.2), you can now pre-select what screen resolution you'd like to use for the virtual screen. |
| 147 | + |
| 148 | +This is done by utilising a pre-made OVMF variable file, with the desired screen resolution built in. Based on what you choose, the corresponding OVMF variable file will be used by AutoPilot to complete setup. |
| 149 | + |
| 150 | +The default resolution is **1280x720** and is recommended for most users - at least until macOS is installed. However, for a more "native" look, you can choose your monitor's screen resolution if it's supported. This means that in full screen mode, the VM will be running native to your whole screen. |
| 151 | + |
| 152 | +Custom values are not supported. When inputting a value at this stage, you will be given a list of supported resolutions to select from. You must then type the number next to the corresponding resolution to select it, *do not type the resolution itself*. |
| 153 | + |
| 154 | +**NOTE: This becomes irrelevant if you use GPU passthrough. Virtual screens are replaced by your physical monitors and their EDID data, which defines available resolutions. This stage is only useful for those not interested in using passthrough.** |
| 155 | + |
| 156 | +| **Default** | Accepted | _Examples_ | |
| 157 | +|:-----------:|:-----------------------------------------------------------------------------------------------:|:---------------------:| |
| 158 | +| 1280x720 | 800x600<br>1024x768<br>1280x720<br>1280x1024<br>1440x900<br>1920x1080<br>2560x1440<br>3840x2160 | 1024x768<br>1920x1080 | |
| 159 | + |
| 160 | +*** |
| 161 | +## Review your preferences |
| 162 | +You'll now get a chance to see your choices displayed in the form of a summary screen. An example of this screen can be found below: |
| 163 | + |
| 164 | + |
| 165 | + |
| 166 | +From here, you can confirm and continue, go back and change your settings, start over, or exit entirely. |
| 167 | + |
| 168 | +*** |
| 169 | +## Process checklist |
| 170 | +The process checklist is displayed upon confirming your preferences, in the form of a traffic light system. |
| 171 | + |
| 172 | +| **Red** | **Yellow** | **Green** | |
| 173 | +|:---------------:|:-----------:|:---------:| |
| 174 | +| Not yet started | In progress | Complete | |
| 175 | + |
| 176 | + |
| 177 | + |
| 178 | +If a sub-operation is required, this will be indicated by a dropdown arrow underneath the current parent operation. |
| 179 | + |
| 180 | +*** |
| 181 | +## Summary |
| 182 | +After everything has been completed without issue, you will be presented with a small summary view of what your boot config script is called, the command you can use to run it, and the time it took to complete AutoPilot (speedrunning anyone?). |
| 183 | + |
| 184 | + |
| 185 | + |
| 186 | +You'll also receive the option to boot the file straight away, open it in your default text handler (v0.9.2 or later), or exit the program. |
| 187 | + |
0 commit comments