Revert "Prepare for documentation overhaul"

This reverts commit 384ed03.
Coopydood · Oct 2, 2024 · f0cd39e · f0cd39e
1 parent 6ad5c4e
commit f0cd39e
Show file tree

Hide file tree

Showing 103 changed files with 4,549 additions and 211 deletions.
diff --git a/docs/AutoPilot.md b/docs/AutoPilot.md
@@ -0,0 +1,246 @@
+## Introduction
+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. 
+
+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.**
+
+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. 
+
+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.
+
+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.
+***
+> [!IMPORTANT]
+> Any "Accepted" values with a **bold** suffix indicate that you must include it when inputting your custom value into AutoPilot, such as file extensions.
+
+***
+## 1. Name your config file
+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 `-`.
+
+| **Default** |     Accepted    |                  _Examples_                  |
+|:-----------:|:---------------:|:--------------------------------------------:|
+|   boot.sh   | [string]**.sh** | macOS.sh<br>macOS-1015.sh<br>ultimate_kvm.sh |
+
+***
+## 2. Set target OS
+As warned in an older version of this document, modern versions of ULTMOS now **do** rely on this setting quite a bit. It is responsible for the following:
+
+- Naming
+- Main menu shortcut
+- CPU model selection
+- Network adapter selection
+- OpenCore image selection
+- macOS Recovery download
+- Discord rich presence
+
+You no longer need to type the target OS version. As of [v0.9.6](https://github.com/Coopydood/ultimate-macOS-KVM/releases/tag/v0.9.6), this stage presents a list of macOS versions to choose from, ranging from **macOS High Sierra** (10.13) to **macOS Sonoma** (14).
+
+You can even select legacy versions of OS X if you wish, ranging from **Mac OS X Lion** (10.7) to **macOS Sierra** (10.12).
+
+***
+## 3. Set number of CPU cores
+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.
+
+| **Default** | Accepted |  _Examples_ |
+|:-----------:|:--------:|:-----------:|
+|      2      | [number] | 4<br>6<br>8 |
+
+***
+## 4. Set number of CPU threads
+Similar to the previous step, your guest needs **virtual threads** to work with.
+
+**THIS VALUE IS A MULTIPLIER.** This is calculated as **_virtual cores_ ✕ _virtual threads_**. 
+
+For example, if you wanted a total of 4 virtual cores and 8 virtual threads, you would input 2 here. (4 ✕ [_**2**_] = 8)
+
+If this confuses you - and I don't blame you, I've confused myself - then leave this value as it is.
+
+| **Default** | Accepted | _Examples_ |
+|:-----------:|:--------:|:----------:|
+|      2      | [number] |   1<br>2   |
+
+***
+## 5. Set CPU model
+This sets the model of the virtual CPU, and subsequently what the guest OS recognizes it as. The default is now determined partly by your *target OS*.
+
+> [!WARNING]
+> **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.
+
+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.
+
+| **Default**        |   Accepted  |      _Examples_      |
+|:------------------:|:-----------:|:--------------------:|
+|    Haswell-noTSX   | [cpu_model] | Broadwell<br>IvyLake |
+|                    |     host    |                      |
+
+***
+## 6. Set CPU feature arguments
+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:
+
+> [!WARNING]
+> **Don't change this unless you know what you're doing.**
+
+|                       **Default**                       |       Accepted      |    _Examples_    |
+|:-------------------------------------------------------:|:-------------------:|:----------------:|
+| +ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check |        +[arg]       |       +kvm       |
+|                                                         | +[arg1],+[arg2] ... | +avx,+kvm,+ssse3 |
+
+***
+## 7. Set amount of allocated RAM
+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. 
+
+> [!NOTE]
+> My only recommendation would be: [_total host RAM_] − [_host idle RAM usage_] − 1GB >= **total virtual RAM**
+
+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)
+
+| **Default** |    Accepted   |    _Examples_   |
+|:-----------:|:-------------:|:---------------:|
+|      4G     | [number]**G** | 2G<br>8G<br>16G |
+
+***
+## 8. Create or add virtual disk
+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. 
+
+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.
+
+> [!NOTE]
+> As of **v0.11.0**, you can now switch to using a physical disk on your host. See *stage 8.1*.
+
+> [!NOTE]
+> As of **v0.10.4**, you can now select an existing virtual qcow2 disk file without making a new one.
+
+> [!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.
+
+| **Default** |    Accepted   |      _Examples_     |
+|:-----------:|:-------------:|:-------------------:|
+|     80G     | [number]**G** | 60G<br>120G<br>256G |
+
+### 8.1 Use a physical disk (advanced)
+
+Instead of a virtual disk, you can use a physical disk attached to your host. Before using a physical disk, you should understand the following:
+
+- The entire disk and its contents are exposed to the guest
+- The guest will have full write access to the disk
+- For NVMe drives, you should use PCI passthrough instead
+
+>[!TIP] 
+> To list available disk IDs, run
+> ``$ ls /dev/disk/by-id/`` in a new terminal.
+
+You must enter a valid disk ID. **Do NOT include the path**.
+e.g. "ata-SATA_SSD_55BD071B194500305381"
+
+
+***
+## 9. Virtual disk type
+
+In **v0.10.5** and later, you can now select what type of storage you'd like the virtual drive to present itself as. 
+
+You can select from **HDD** (default), **SSD**, and even **NVMe**. Each option changes the way the virtual disk is connected to the virtual machine, including whether or not it is solid state.
+
+Switching the virtual disk type to **SSD** can be beneficial if your virtual disk file is being stored on a real SSD, as the guest OS inside the VM will behave with solid state storage in mind - enabling features such as TRIM.
+
+> [!NOTE]
+> This option is unlikely to affect performance. Its purpose is to allow you to properly represent your storage medium to the guest OS.
+
+> [!NOTE]
+> Changing the virtual disk type to *SSD* or *NVMe* while storing the disk file on a host HDD yields no advantages and would be purely cosmetic.
+
+***
+## 10. Set network adapter model
+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. 
+
+**Based on your target OS you chose earlier, the default option will auto-select the best model for your macOS version.** 
+
+You can still override this if you'd like, but for most people, whatever is auto-selected will be fine.
+
+|  **Default**  |     Accepted    |     _Examples_    |
+|:-------------:|:---------------:|:-----------------:|
+| e1000-82545em | [adapter_model] | e1000m<br>vmxnet3 |
+|    vmxnet3    |                 |                   |
+
+***
+## 11. Network MAC address
+The virtual network adapter needs a virtual MAC address to identify it. 
+
+**The default is fine unless you intend on using features such as iMessage and FaceTime, as these services require specific MAC address values.**
+
+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.
+
+|    **Default**    |                Accepted               |                          _Examples_                         |
+|:-----------------:|:-------------------------------------:|:-----------------------------------------------------------:|
+| 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 |
+
+***
+## 12. macOS Recovery image file
+To install macOS, you'll need an image of the macOS Recovery. 
+
+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. This becomes handy when using full offline installer ``InstallESD.dmg`` images.
+
+You can also choose to skip this step, such as if you are simply re-generating the AutoPilot config for an existing install.
+
+|   **Default**  |     Accepted    |              _Examples_             |
+|:--------------:|:---------------:|:-----------------------------------:|
+| BaseSystem.img | [file_name].img | BaseSystem.img<br>macOSRecovery.img |
+|                | [file_name].dmg |   BaseSystem.dmg<br>InstallESD.dmg  |
+
+***
+## 13. Screen resolution
+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.
+
+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. 
+
+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.
+
+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*.
+
+> [!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.**
+
+| **Default** |                                             Accepted                                            |       _Examples_      |
+|:-----------:|:-----------------------------------------------------------------------------------------------:|:---------------------:|
+|   1280x720  | 800x600<br>1024x768<br>1280x720<br>1280x1024<br>1440x900<br>1920x1080<br>2560x1440<br>3840x2160 | 1024x768<br>1920x1080 |
+
+***
+## 14. Generate XML file
+As of [v0.9.3](https://github.com/Coopydood/ultimate-macOS-KVM/releases/tag/v0.9.3), XML files can be generated through conversion of a valid AutoPilot config file using the **XML Conversion tool**. This can be accessed through the **Extras** menu. 
+
+However, with the [v0.9.5](https://github.com/Coopydood/ultimate-macOS-KVM/releases/tag/v0.9.5) update, this functionality is also built right in as an AutoPilot stage.
+
+If you choose, you can have AutoPilot automatically create an XML file alongside your regular boot config script as part of the AutoPilot flow. You'll then be prompted to import it upon completion, for use within Virtual Machine Manager (virt-manager), for easy GUI access.
+
+This stage is completely optional and can be skipped. You can always use the standalone XML conversion tool to convert an AutoPilot script at any time, from the Extras menu.
+
+***
+## Review your preferences
+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:
+
+![AutoPilot summary screen](https://github.com/Coopydood/ultimate-macOS-KVM/assets/39441479/996fb2b5-28ef-4949-bbc3-4107193b1187)
+
+From here, you can confirm and continue, go back and change your settings, start over, or exit entirely.
+
+***
+## Process checklist
+The process checklist is displayed upon confirming your preferences, in the form of a traffic light system.
+
+|     **Red**     |  **Yellow** | **Green** |
+|:---------------:|:-----------:|:---------:|
+| Not yet started | In progress |  Complete |
+
+![AutoPilot progress screen, showing traffic light system](https://github.com/Coopydood/ultimate-macOS-KVM/assets/39441479/b6390adc-62ff-4a91-bf00-a9b911a5cb29)
+
+If a sub-operation is required, this will be indicated by a dropdown arrow underneath the current parent operation.
+
+***
+## Summary
+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?).
+
+![AutoPilot post-success screen.](https://github.com/Coopydood/ultimate-macOS-KVM/assets/39441479/a95f7741-b029-4596-be99-c9fa8b51bb9f)
+
+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.
+
diff --git a/docs/Credits.md b/docs/Credits.md
@@ -0,0 +1,15 @@
+## Credits
+
+While I am the creator of these automation/ease-of-use scripts, this project is not possible without both the prior and current works of some very talented people. The people who have tested the project are also included.
+
+- **[Dortania](https://github.com/Dortania)** 》 Extensive documentation and Hackintosh development.
+- **[Kholia](https://github.com/kholia)** 》 Development of scripts and documentation. ultimate-macOS-KVM is intended as an extension to [OSX-KVM](https://github.com/kholia/OSX-KVM).
+- **[thenickdude](https://github.com/thenickdude)** 》 Personal support throughout my KVM misadventures and countless community contribs. Cheers.
+- **[vu1tur]([email protected])** 》 Open source dmg to img conversion tool; used and bundled by this project.
+- **[Eversiege](https://github.com/eversiege)** 》 Support and testing, та мій улюблений українець.
+- **[CyberneticSquid](https://github.com/cyberneticsquid)** 》 Testing for me at stupid-o'-clock because he's a cool Aussie.
+- **[Cake](https://github.com/cam-jm)** 》 Another Aussie testing for me in the middle of my sleep-deprived nights, with a slight obsession over cake.
+- **[Hyperchromiac](https://github.com/hyperchromiac)** 》 My personal constitution-munching American. Legend has it that I live in his attic, although even I'm not sure. Love this guy either way.
+- **[Kaz](https://github.com/Eaz11)** 》 Other than his brilliant English accent's pronounciations (including "macOS Syria"), he's done extensive testing. Say hi to your nephew for me.
+- **[GigantTech](https://twitter.com/TechGigant)** 》 Moderately annoying German guy that I convinced to install Linux subsequently letting him test my project. It's free real estate!
+- **[Hummenix](https://github.com/Hummenix)** 》Testing of ULTMOS across different Linux distros.