diff --git a/.gitignore b/.gitignore index ed4ce0c..3fbca7b 100644 --- a/.gitignore +++ b/.gitignore @@ -43,7 +43,7 @@ boot/opencore-image-ng.sh boot/mnt docs/.screenshots BaseSystem.dmg -.gitignore + boot.xml ovmf/OVMF_VARS_PT.fd resources/.notices @@ -56,4 +56,6 @@ blobs/user/.noBaseSystemReminder resources/.nrsMode resources/BaseSystem.dmg resources/BaseSystem.img -testVM/ \ No newline at end of file +testVM/ +docs/_site +docs/.history diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..6240da8 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,21 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store diff --git a/docs/_config.yml b/docs/_config.yml index c8ab835..4786992 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -42,7 +42,7 @@ exclude: - fixtures/ # Set a path/url to a logo that will be displayed instead of the title -logo: "assets/ULTMOS.png" +logo: "assets/images/ULTMOS.png" # Enable or disable the site search # Supports true (default) or false diff --git a/docs/_includes/components/header.html b/docs/_includes/components/header.html index f9c3386..5b6c96d 100644 --- a/docs/_includes/components/header.html +++ b/docs/_includes/components/header.html @@ -4,8 +4,8 @@ {% else %}
{% endif %} - {% include header_custom.html %} {% if site.aux_links %} {% include components/aux_nav.html %} {% endif %} + {% include header_custom.html %} diff --git a/docs/_includes/css/just-the-docs.scss.liquid b/docs/_includes/css/just-the-docs.scss.liquid index 2eb480d..c04e019 100644 --- a/docs/_includes/css/just-the-docs.scss.liquid +++ b/docs/_includes/css/just-the-docs.scss.liquid @@ -4,7 +4,8 @@ $logo: "{{ site.logo | relative_url }}"; @import "./support/support"; @import "./custom/setup"; @import "./color_schemes/light"; -{% unless include.color_scheme == "light" %} +@import "./color_schemes/dark"; +{% unless include.color_scheme == "dark" %} @import "./color_schemes/{{ include.color_scheme }}"; {% endunless %} @import "./modules"; diff --git a/docs/_includes/header_custom.html b/docs/_includes/header_custom.html index e69de29..c01b027 100644 --- a/docs/_includes/header_custom.html +++ b/docs/_includes/header_custom.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/_includes/js/custom.js b/docs/_includes/js/custom.js index e69de29..7b44a9b 100644 --- a/docs/_includes/js/custom.js +++ b/docs/_includes/js/custom.js @@ -0,0 +1,19 @@ +onload = function() { + // JavaScript to toggle between light and dark mode + const toggleButton = document.getElementById('theme-toggle'); + const bodyElement = document.body; + + // Check for saved mode preference in localStorage + const currentTheme = localStorage.getItem('theme'); + if (currentTheme === 'light') { + bodyElement.classList.toggle('light-mode'); + } + + // Toggle mode and save preference + toggleButton.addEventListener('click', () => { + bodyElement.classList.toggle('light-mode'); + + const theme = bodyElement.classList.contains('light-mode') ? 'light' : 'dark'; + localStorage.setItem('theme', theme); // Save the preference + }); +} \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 0cc900a..d238942 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -7,39 +7,41 @@ {% include head.html %} - Skip to main content - {% include icons/icons.html %} - {% if page.nav_enabled == true %} - {% include components/sidebar.html %} - {% elsif layout.nav_enabled == true and page.nav_enabled == nil %} - {% include components/sidebar.html %} - {% elsif site.nav_enabled != false and layout.nav_enabled == nil and page.nav_enabled == nil %} - {% include components/sidebar.html %} - {% endif %} -
- {% include components/header.html %} -
- {% include components/breadcrumbs.html %} -
-
- {% if site.heading_anchors != false %} - {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %} - {% else %} - {{ content }} - {% endif %} +
+ Skip to main content + {% include icons/icons.html %} + {% if page.nav_enabled == true %} + {% include components/sidebar.html %} + {% elsif layout.nav_enabled == true and page.nav_enabled == nil %} + {% include components/sidebar.html %} + {% elsif site.nav_enabled != false and layout.nav_enabled == nil and page.nav_enabled == nil %} + {% include components/sidebar.html %} + {% endif %} +
+ {% include components/header.html %} +
+ {% include components/breadcrumbs.html %} +
+
+ {% if site.heading_anchors != false %} + {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %} + {% else %} + {{ content }} + {% endif %} - {% if page.has_toc != false %} - {% include components/children_nav.html %} - {% endif %} -
- {% include components/footer.html %} + {% if page.has_toc != false %} + {% include components/children_nav.html %} + {% endif %} +
+ {% include components/footer.html %} +
+ {% if site.search_enabled != false %} + {% include components/search_footer.html %} + {% endif %}
- {% if site.search_enabled != false %} - {% include components/search_footer.html %} - {% endif %} - + {% if site.mermaid %} {% include components/mermaid.html %} {% endif %} diff --git a/docs/_sass/base.scss b/docs/_sass/base.scss index afa67a4..419e197 100644 --- a/docs/_sass/base.scss +++ b/docs/_sass/base.scss @@ -20,7 +20,6 @@ body { font-size: inherit; line-height: $body-line-height; color: $body-text-color; - background-color: $body-background-color; overflow-wrap: break-word; } diff --git a/docs/_sass/color_schemes/dark.scss b/docs/_sass/color_schemes/dark.scss index 6d0999b..f98477b 100644 --- a/docs/_sass/color_schemes/dark.scss +++ b/docs/_sass/color_schemes/dark.scss @@ -4,7 +4,7 @@ $body-heading-color: $grey-lt-000; $body-text-color: $grey-lt-300; $link-color: $blue-000; $nav-child-link-color: $grey-dk-000; -$sidebar-color: $grey-dk-300; +$sidebar-color: rgba($grey-dk-300, 0.4); $base-button-color: $grey-dk-250; $btn-primary-color: $blue-200; $code-background-color: #31343f; // OneDarkJekyll default for syntax-one-dark-vivid @@ -13,6 +13,6 @@ $feedback-color: darken($sidebar-color, 3%); $table-background-color: $grey-dk-250; $search-background-color: $grey-dk-250; $search-result-preview-color: $grey-dk-000; -$border-color: $grey-dk-200; +$border-color: $grey-dk-300; @import "./vendor/OneDarkJekyll/syntax"; // this is the one-dark-vivid atom syntax theme diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss index ac8445a..a7c60ae 100644 --- a/docs/_sass/custom/custom.scss +++ b/docs/_sass/custom/custom.scss @@ -1 +1,74 @@ // custom SCSS (or CSS) goes here + +html { + + position: relative; + background-image: url("https://static1.squarespace.com/static/5e949a92e17d55230cd1d44f/t/666797c50267ef33983aa221/1718065110482/SequoiaDark.png"); + background-position: center center; + background-attachment: fixed; + background-size: cover; + background-repeat: no-repeat; + height: 100vh; + +} + +.main { + + background-color: rgba($body-background-color, 0.94); + backdrop-filter: blur(500px); + min-height: 100vh; + +} + + +.side-bar { + + background-color: rgba($sidebar-color, 0.7); + backdrop-filter: blur(25px); + +} + +.light-mode { + + @import "../color_schemes/light.scss"; + + background-image: url(https://media.discordapp.net/attachments/764964269460029442/1293703419483394159/SequoiaLight.png?ex=670856b3&is=67070533&hm=4898869ebea28d70fafa001b371d4acd7f5489b1b1cfba1e6afcc3e0a2d32396&=&format=webp&quality=lossless); + background-position: center center; + background-attachment: fixed; + background-size: cover; + background-repeat: no-repeat; + + .main { + + background-color: rgba($white, 0.6); + backdrop-filter: blur(500px); + min-height: 100vh; + + } + + .main-content, + .footer { +// @sproott - I was here + + h1, + h2, + h3, + h4, + h5 { + + color: $grey-dk-300; + + } + + color: $grey-dk-300; + + } + + .side-bar { + + background-color: rgba($white, 0.7); + backdrop-filter: blur(25px); + + } + +} diff --git a/docs/_sass/layout.scss b/docs/_sass/layout.scss index 4cc6ee4..135bb2f 100644 --- a/docs/_sass/layout.scss +++ b/docs/_sass/layout.scss @@ -4,7 +4,6 @@ z-index: 0; display: flex; flex-wrap: wrap; - background-color: $sidebar-color; @include mq(md) { flex-flow: column nowrap; @@ -16,7 +15,6 @@ } @include mq(lg) { - width: calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width}); min-width: $nav-width; } @@ -60,13 +58,14 @@ @include mq(md) { position: relative; - max-width: $content-width; } } .main-content-wrap { padding-top: $gutter-spacing-sm; padding-bottom: $gutter-spacing-sm; + background-attachment: fixed; + @include container; @@ -121,7 +120,6 @@ @include mq(md) { height: $header-height; max-height: $header-height; - border-bottom: $border $border-color; } } diff --git a/docs/_sass/support/_variables.scss b/docs/_sass/support/_variables.scss index 0b051ff..cd747bc 100644 --- a/docs/_sass/support/_variables.scss +++ b/docs/_sass/support/_variables.scss @@ -101,7 +101,7 @@ $nav-width-md: 15.5rem !default; $nav-list-item-height: $sp-6 !default; $nav-list-item-height-sm: $sp-8 !default; $nav-list-expander-right: true; -$content-width: 50rem !default; +$content-width: 30rem !default; $header-height: 3.75rem !default; $search-results-width: $content-width - $nav-width !default; $transition-duration: 400ms; diff --git a/docs/assets/css/just-the-docs-dark.scss b/docs/assets/css/just-the-docs-dark.scss new file mode 100644 index 0000000..ac92fb1 --- /dev/null +++ b/docs/assets/css/just-the-docs-dark.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="dark" %} diff --git a/docs/assets/css/just-the-docs-default.scss b/docs/assets/css/just-the-docs-default.scss new file mode 100644 index 0000000..63fde26 --- /dev/null +++ b/docs/assets/css/just-the-docs-default.scss @@ -0,0 +1,8 @@ +--- +--- +{% if site.color_scheme and site.color_scheme != "nil" %} + {% assign color_scheme = site.color_scheme %} +{% else %} + {% assign color_scheme = "light" %} +{% endif %} +{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %} diff --git a/docs/assets/css/just-the-docs-light.scss b/docs/assets/css/just-the-docs-light.scss new file mode 100644 index 0000000..ac69688 --- /dev/null +++ b/docs/assets/css/just-the-docs-light.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="light" %} diff --git a/docs/assets/ULTMOS.png b/docs/assets/images/ULTMOS.png similarity index 100% rename from docs/assets/ULTMOS.png rename to docs/assets/images/ULTMOS.png diff --git a/docs/assets/js/just-the-docs.js b/docs/assets/js/just-the-docs.js new file mode 100644 index 0000000..d249b6d --- /dev/null +++ b/docs/assets/js/just-the-docs.js @@ -0,0 +1,618 @@ +--- +layout: null +--- +(function (jtd, undefined) { + +// Event handling + +jtd.addEvent = function(el, type, handler) { + if (el.attachEvent) el.attachEvent('on'+type, handler); else el.addEventListener(type, handler); +} +jtd.removeEvent = function(el, type, handler) { + if (el.detachEvent) el.detachEvent('on'+type, handler); else el.removeEventListener(type, handler); +} +jtd.onReady = function(ready) { + // in case the document is already rendered + if (document.readyState!='loading') ready(); + // modern browsers + else if (document.addEventListener) document.addEventListener('DOMContentLoaded', ready); + // IE <= 8 + else document.attachEvent('onreadystatechange', function(){ + if (document.readyState=='complete') ready(); + }); +} + +// Show/hide mobile menu + +function initNav() { + jtd.addEvent(document, 'click', function(e){ + var target = e.target; + while (target && !(target.classList && target.classList.contains('nav-list-expander'))) { + target = target.parentNode; + } + if (target) { + e.preventDefault(); + target.ariaPressed = target.parentNode.classList.toggle('active'); + } + }); + + const siteNav = document.getElementById('site-nav'); + const mainHeader = document.getElementById('main-header'); + const menuButton = document.getElementById('menu-button'); + + disableHeadStyleSheets(); + + jtd.addEvent(menuButton, 'click', function(e){ + e.preventDefault(); + + if (menuButton.classList.toggle('nav-open')) { + siteNav.classList.add('nav-open'); + mainHeader.classList.add('nav-open'); + menuButton.ariaPressed = true; + } else { + siteNav.classList.remove('nav-open'); + mainHeader.classList.remove('nav-open'); + menuButton.ariaPressed = false; + } + }); + + {%- if site.search_enabled != false and site.search.button %} + const searchInput = document.getElementById('search-input'); + const searchButton = document.getElementById('search-button'); + + jtd.addEvent(searchButton, 'click', function(e){ + e.preventDefault(); + + mainHeader.classList.add('nav-open'); + searchInput.focus(); + }); + {%- endif %} +} + +// The element is assumed to include the following stylesheets: +// - a to /assets/css/just-the-docs-head-nav.css, +// with id 'jtd-head-nav-stylesheet' +// - a \ No newline at end of file diff --git a/docs/dimensional-debris/src/assets/ULTMOS.png b/docs/dimensional-debris/src/assets/ULTMOS.png new file mode 100644 index 0000000..03232a3 Binary files /dev/null and b/docs/dimensional-debris/src/assets/ULTMOS.png differ diff --git a/docs/dimensional-debris/src/assets/bannerAlphaBasic.png b/docs/dimensional-debris/src/assets/bannerAlphaBasic.png new file mode 100644 index 0000000..032efb3 Binary files /dev/null and b/docs/dimensional-debris/src/assets/bannerAlphaBasic.png differ diff --git a/docs/dimensional-debris/src/assets/houston.webp b/docs/dimensional-debris/src/assets/houston.webp new file mode 100644 index 0000000..930c164 Binary files /dev/null and b/docs/dimensional-debris/src/assets/houston.webp differ diff --git a/docs/dimensional-debris/src/components/Sidebar.astro b/docs/dimensional-debris/src/components/Sidebar.astro new file mode 100644 index 0000000..2aa4bfe --- /dev/null +++ b/docs/dimensional-debris/src/components/Sidebar.astro @@ -0,0 +1,14 @@ +--- +const files = await Astro.fetchContent('../content/docs/changelogs/**/*.md'); + +// Sort by filenames in descending order +const sortedFiles = files.sort((a, b) => b.fileName.localeCompare(a.fileName)); +--- + + \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/config.ts b/docs/dimensional-debris/src/content/config.ts new file mode 100644 index 0000000..45f60b0 --- /dev/null +++ b/docs/dimensional-debris/src/content/config.ts @@ -0,0 +1,6 @@ +import { defineCollection } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ schema: docsSchema() }), +}; diff --git a/docs/dimensional-debris/src/content/docs/AutoPilot.md b/docs/dimensional-debris/src/content/docs/AutoPilot.md new file mode 100644 index 0000000..d074cd5 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/AutoPilot.md @@ -0,0 +1,250 @@ +--- +title: AutoPilot +--- + +## 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
macOS-1015.sh
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
6
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
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
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
8G
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
120G
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
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
00:16:ca:00:27:09
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
macOSRecovery.img | +| | [file_name].dmg | BaseSystem.dmg
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
1024x768
1280x720
1280x1024
1440x900
1920x1080
2560x1440
3840x2160 | 1024x768
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/dimensional-debris/src/content/docs/Credits.md b/docs/dimensional-debris/src/content/docs/Credits.md new file mode 100644 index 0000000..83ada59 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/Credits.md @@ -0,0 +1,19 @@ +--- +title: Credits +--- + +## 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](to@vu1tur.eu.org)** 》 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. diff --git a/docs/dimensional-debris/src/content/docs/Extras.md b/docs/dimensional-debris/src/content/docs/Extras.md new file mode 100644 index 0000000..74ffa0c --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/Extras.md @@ -0,0 +1,76 @@ +--- +title: Extras +--- + +## Extras +### extras.py + +> [!WARNING] +> This script should not be run on its own. +> +> It should be run through the `main.py` file instead. Use the **E** option at the main menu. + + + +This page will go over some of the features in the Extras menu, without too much detail. + +*** + +## 1. Create and import XML file + +This option allows you to automatically convert a QEMU config script previously generated by AutoPilot into an XML file compatible with **virt-manager** (Virtual Machine Manager), which is a GUI frontend that makes management of your VMs easier and nicer to work with. + +After conversion, you'll have the option to automatically import the XML file into virt-manager. + +To learn more about the XML Converter, visit [this page](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/XML-Converter). + +*** + +## 2. OpenCore Configuration Assistant + +This tool allows you to mount your virtual OpenCore image as a disk on your host system, allowing you to edit the contents without ever booting your VM. + +*** + +## 3. macOS Boot Argument Editor + +This tool allows you to seamlessly edit your macOS OpenCore boot arguments - letting you apply patches for things like GPU output. + +It even includes a feature called **AutoPatch**, containing a list of known boot argument patches. You can select one, and the tool will instantly apply the relevant boot patch for your system. For example, you can apply the **Navi RX 5000 / 6000 black screen** patch automatically! + +For more on this, and available patches, visit [this page](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/macOS-Boot-Argument-Editor). + +*** + +## 4. GRUB Argument Editor + +For users who use GRUB to boot their host's Linux install, setting the right kernel parameters can sometimes be a daunting mess. With this tool, most of this stress is taken care of automatically, through the auto-configuration of parameters **based on your specific system!** + +Created by @Hyperchromiac. + +*** + +## 5. Generate SMBIOS / Serial Number + +ULTMOS now has built-in support for CorpNewt's [GenSMBIOS](https://github.com/corpnewt/GenSMBIOS) script, allowing you to automatically change your OpenCore's SMBIOS model and serial number - so you can customise the virtual Mac model and log into iServices, etc. + +*** + +## R. Restore tools... + +This opens a seperate menu providing options to restore various parts of the repository to defaults. + +Great for troubleshooting common issues and covering up your mess. + +*** + +## I. Report an issue... + +Opens a new issue page on the GitHub repo in your default browser. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/FAQs.md b/docs/dimensional-debris/src/content/docs/FAQs.md new file mode 100644 index 0000000..2223f8e --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/FAQs.md @@ -0,0 +1,252 @@ +--- +title: Frequently Asked Questions (FAQs) +--- + +## Frequently Asked Questions (FAQs) +### Some of the most asked questions, including the basics + +#### Introduction + +Scripts? Configs? QEMU arguments? A *"qcow"* file? Moo? If you need a little help wrapping your head around this stuff, this is the right document! Find a question from the list below and click the dropdown to see my expertly-crafted answer. + +*** +
What is the purpose of this project?
 + +*ultimate-macOS-KVM* was created to try and ease the complications of creating a macOS virtual machine through KVM, including some of the more advanced tasks, like GPU passthrough. + +
+ +
How does this work?
 + +Written in Python, this project uses various scripts to automate the creation and management of a macOS virtual machine, using QEMU and KVM. + +The scripts are run in terminal-space. Scripts included in the project intended on being used by the user present with terminal UIs (TUIs), creating a friendly approach to the command line. + +
+ +
It's for noobs, right?
 + +It can be, sure. But *ultimate-macOS-KVM* is designed for everyone. You may well be a noob, and that's okay, but you might also be a professional **nerd** who knows everything about everything. Either way, this project was made for you. + +While there is a focus on user-friendliness, there are plenty of advanced features and functionality present within the project. For example, did you know that the built in updater can upgrade and downgrade to *any version* of the project using command arguments? Neither did I! + +Furthermore, it's as f*ck-up-proof as possible, with tools designed to help you recover from such misadventures without losing valuable files, such as a soft reset of the virtual NVRAM, which can be used to fix common bootloader issues. Or, for the hardcore misintellectual, you can even download and reset the *entire* project from *within* the project. Pure mental- *for* the pure mental. + +
+ +
Why should I use this?
 + +Idk. But, if you're reading this you're clearly interested, so I'll try convince you. + +The main "selling point" of the project is probably **AutoPilot**, which is a massive script that can do the following: + +- Guide the user through virtual hardware setup, including explanations +- Automatically changes the recommended defaults based on several factors, including the choices you make +- Load preset files for express setup, no options needed (in development) +- Plenty of granular options for advanced users +- Automatically downloads macOS for you, or you can supply your own image +- __Have a fully-functional KVM-powered macOS VM in under 5 minutes__ +- Sleep deprive the developer of the project + +Additionally, as mentioned in the last section (which I know you read), there's crisis-management built right in, for all those f*cky-wuckies you might have. The project includes a suite of restoration tools that help you attempt virtual machine boot recovery without losing your install and anything in it. + +
+ +
Can my computer run this?
 + +Does it run Crysis? Yes? You're wrong. Anyway, the answer is *probably*. + +Any recent Linux kernel has KVM built right in, meaning you don't have to do any extra setup on that front. + +> [!IMPORTANT] +> You **must** be booting in UEFI mode, and **NOT** legacy BIOS mode. Secure Boot should also ideally be disabled. + +CSM and ROM-BAR may need to be enabled / disabled based on your specific system. See the [gotchas page](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/Gotchas) for more on this. + +All you need to do is install the dependencies and have your hardware meet the requirements, both listed [here](https://github.com/Coopydood/ultimate-macOS-KVM#requirements). Then, just follow the small guide included [here](https://github.com/Coopydood/ultimate-macOS-KVM#getting-started). You can choose any Linux distro that you want, but individual installations of packages will likely differ between different distros (apt, pacman, rpm, etc.). + +There are also a few automatic system checkers built in, included in the `./scripts/extras/` folder and can be run seperately from the project - or using the included submenu in v0.9.0 or later. These can check the following: + +- Whether your system is ready for basic KVM +- If your system is set up for VFIO-PCI passthrough +- The compatibility of your installed GPUs with macOS +- IOMMU grouping +- VFIO-PCI kernel driver device bindings +- VFIO-PCI IDs of installed hardware + +
+ +
What is a "qcow2" file?
 + +Moof! (Clarus reference, anyone?) + +A ``.qcow2`` file is simply a virtual hard disk file used mainly by QEMU/KVM. + +The VMware equivalent would be a ``.vmdk`` file. + +The VirtualBox equivalent would be a ``.vdi`` or ``.vdk`` file. + +
+ +
What are QEMU arguments?
 + +WHY HAS MY DAD BEEN GONE SO LONG? WORKING WITH QEMU AGAIN?! +NO MICHAEL! HE JUST WENT TO GET THE MILK- + +Oh, sorry, not that kind of QEMU argument! + +The QEMU arguments are simply the list of variables passed on to the ``qemu-system-x86_64`` program, used to set up your virtual machine. + +The arguments themselves shouldn't be edited by the user, as they've been pre-programmed to work out-of-the-box. + +They look similar to this: + +``` +args=( +-global ICH9-LPC.acpi-pci-hotplug-with-bridge-support=off +-enable-kvm -m "$ALLOCATED_RAM" -cpu "$CPU_MODEL",kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on,"$CPU_FEATURE_ARGS" +-machine q35 +-usb -device usb-kbd -device usb-tablet #USB_DEV +-smp "$CPU_THREADS",cores="$CPU_CORES",sockets="$CPU_SOCKETS" +-device usb-ehci,id=ehci +-device qemu-xhci,id=xhci +-device pcie-root-port,bus=pcie.0,slot=1,x-speed=16,x-width=32 +... +) +``` + +
+ +
What do you mean by "scripts" and "configs"?
 + +When the project mentions "scripts", it means either *the Python files used to run the program*, or *the user-generated shell scripts used to boot a virtual machine.* + +When the project mentions "configs", it's typically referring to *files generated by AutoPilot*, in the form of shell scripts ending in ``.sh``. These were generated based on your specific configuration, hence the naming. + +
+ +
How do I enable/disable Discord rich presence?
 + +To show off your AutoPilot progress or virtual machine status on your Discord profile, you have to enable **Discord rich presence**. + +> [!NOTE] +> You must have the ``pypresence`` dependency installed. This can be done via a system wide package, ``python-pypresence``, or by using ``pip install pypresence`` for external environments. + +The project will detect whether or not this is installed when you run AutoPilot, and marks the generated script accordingly. If you create an AutoPilot script with the dependency installed, your generated script will automatically have Discord rich presence enabled, and you don't have to do anything. + +If you install the dependency **after** generating a script - don't worry, it's still easy to enable. Simply open your generated boot script, and look at the ULTMOS variable block. Find the following line: + +```sh +DISCORD_RPC=0 +``` + +To enable rich presence, change ``0`` to ``1``, and vice versa to disable it. + +If you don't want to show your status when running AutoPilot itself, you can manually run the AutoPilot script with a disable argument: + +```sh +$ ./scripts/autopilot.py --disable-rpc +``` + +
+ +
I'm here for GPU (or any PCI) passthrough!
 + +Great! The project can assist you with this too. + +There's a built-in tool called the **VFIO-PCI Passthrough Assistant**, which - similarly to *AutoPilot* - guides you through the process of configuring your devices for VFIO-PCI passthrough. + +The full guide for this tool and passthrough in general can be found [here](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/Passthrough). + +
+ + + +
What's inside all the folders?
 + +Well, fun stuff, but there's some that you shouldn't touch unless you'd like to help improve the project. + +Everything in the ``resources`` folder should be left alone, as the project needs the stuff in here to function properly. Editing or misplacing these files will likely break the project. If you think this has happened by accident or through your reckless behaviour, you can use the built in restoration script to restore the project files back to their working state, without losing your data or having to re-clone the repository. Don't worry, your stupidity is safe with me. + +The files in the aptly-named ``scripts`` folder are, well, the scripts themselves. Same principle as the `resources` folder - no touchy unless you know how to touchy. + +Files in the ``boot`` folder are generated after running AutoPilot. They consist of the OpenCore boot image and its unpackaged files. You can't really edit these even if you wanted to, except from the OpenCore image, which **you should do** from within macOS. A guide on this can be found [here](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/OpenCore). + +The ``blobs`` folder contains nothing until AutoPilot is run. This is where AutoPilot stores your choices, instead of using variables. This way, if the process is interrupted for some reason, it can be resumed using the existing files. The contents of these files may also be dictated by an *AutoPilot preset* that you loaded. Do NOT delete the blobs in the ``user`` folder, as these are accessed by other areas of the project. The blobs in the ``stale`` folder are unused and are stored simply in case the user wants to back them up, but can be safely deleted at any time. + +The ``roms`` folder contains one example GPU VBIOS (AMD Radeon RX 550 Sapphire Pulse), and any other you've used or dumped with the project. If you supply a ROM file in the VFIO-PCI passthrough assistant for example, it will be copied from its original location to this folder for use with QEMU. The original ROM file is not touched. If you use the built-in VBIOS dump tool, the output file is also placed in this folder automatically. You may need to patch a GPU's VBIOS, and this can be done to any ROM file in this folder directly if you wish. The files in this folder can be safely deleted as long as they are no longer used by a script you've made with AutoPilot. If you don't use passthrough, this folder isn't relevant to you. + +The ``ovmf`` folder is also populated only after running AutoPilot. This folder holds the OVMF boot code file, and your customised OVMF variable file - holding information such as boot order, screen resolution, etc. The files in here have a tendancy to become unusable after heavy usage, but this can be easily resolved. However, do **NOT** remove or replace the files yourself. Use the built-in OVMF restore tool, which can be accessed from the main menu. + +Oh, hi mum! I'm on the ``docs`` folder! Well, there's not much to this one as you've evidently already found it, but this folder contains several useful(?) documents surrounding both the project itself and other aspects of using KVM. If you find the way I write documents fills you with a burning hatrid-filled rage, you can delete these files if you want... But, I'll know. I'm like Santa- always watching. + +And finally, the ``internal`` folder. If you see this, run. You shouldn't have it. Oh and by the way, I'll know if you do. ;) + +
+ +
Can I edit the boot config I made with AutoPilot?
 + +Yes, you can. AutoPilot is designed to create a new boot script based on your preferences, but you may desire to change these over time without using AutoPilot again, and it has been designed to allow you to do so. + +The values that can be safely changed by the user are all placed at the top of the generated boot script, like this: + +```sh +ALLOCATED_RAM="8G" +CPU_SOCKETS="1" +CPU_CORES="2" +CPU_THREADS="4" +CPU_MODEL="host" +CPU_FEATURE_ARGS="+ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check" +``` + +As you can see, the values you would have chosen during AutoPilot are inserted into each argument as a string. You can edit the value inside the string (i.e. "8G"), but do **NOT** edit the variable itself (i.e. ALLOCATED_RAM=). In this example, if you wanted to change the virtual RAM from 8 GB to 16 GB, you'd change + +```sh +ALLOCATED_RAM="8G" +``` + +to + +```sh +ALLOCATED_RAM="16G" +``` + +and this would take effect in the VM's configuration the next time it is run. + +Anything below the variables should not be changed, except the designated lines used to attach the macOS recovery image to the VM, or the lines used to enable VNC. You can remove these lines after you've installed macOS, which will stop "macOS Base System" from appearing in your boot menu. To do this, remove the following lines from your config file: + +```sh +############## REMOVE THESE LINES AFTER MACOS INSTALLATION ############### +-drive id=BaseSystem,if=none,file="/home/aaaaaaa/sexytime/BaseSystem.dmg",format=raw +-device ide-hd,bus=sata.4,drive=BaseSystem +########################################################################## +``` + +> [!NOTE] +> You may prefer to comment-out the lines instead, in case you need to re-attach the base system image again later. + +
+ +
Can I use VNC?
 + +If you would prefer to connect to the virtual display using VNC, you can do so! The virtual machine can open a virtual display as a VNC server, running on port ``5900`` of your local host. Uncomment the ``-vnc`` line (remove the # at the start) of your boot config file to enable this: + +```sh +################ UNCOMMENT IF YOU WANT TO USE VNC MONITOR ################ +-vnc 0.0.0.0:1,password=on -k en-us +########################################################################## +``` + +You can then connect to the virtual machine's display using a VNC client, at ``127.0.0.1:5900``, or even remotely using your local/external IP. If you want to connect from outside your network, please make sure you have all the necessary security and hardening before doing this. Basically; don't let me sneak in. + +
+ +*** +I hope you liked reading this document and found it somewhat useful (and maybe even funny). Eversiege watched me write it and liked it, so it's obviously good. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/GettingStarted.md b/docs/dimensional-debris/src/content/docs/GettingStarted.md new file mode 100644 index 0000000..b8614c6 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/GettingStarted.md @@ -0,0 +1,52 @@ +--- +title: Getting Started +--- + + +## Cloning and Permissions +It's easy to get up and running. Simply clone the repo, fix permissions, and run. +Make sure you have **all** [dependencies](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/README.md#requirements) installed before getting started. + +*** + +> [!WARNING] +> As of v0.9.0, the main menu file is now `main.py`. This wiki has been updated to reflect this change. +> If you are on an older project version (<= v0.8.6), this file will still be named `setup.py`. +*** + +``` +git clone https://github.com/Coopydood/ultimate-macOS-KVM +cd ultimate-macOS-KVM +chmod +x main.py +``` +or, do all this with a one-liner: +``` +git clone https://github.com/Coopydood/ultimate-macOS-KVM && cd ultimate-macOS-KVM && chmod +x main.py +``` + +*** + +## Starting Up +To begin using the project, run the `main.py` file found in the root of the repo directory. It can be run using the following command: +``` +./main.py +``` +This is your central hub - a macOS-KVM swiss army knife per se. You should use this script to access any other parts of the project, as the other script files **are not intended to be run directly by the user**. + +When using the script, make sure you are cd'd into the `ultimate-macOS-KVM` repo directory first. Example: +``` +[name@hostname ~]$ cd ultimate-macOS-KVM +[name@hostname ultimate-macOS-KVM]$ ./main.py +``` + +*** +> [!IMPORTANT] +> Do *not* use `sudo`. If you're in the habit of running everything with superuser permissions - break that habit before it breaks you. +> None of my scripts require `sudo` or root permissions. The only exception to this would be when running a config script *with a physical PCI device passed through using VFIO-PCI*, as this may require superuser permissions as you're dealing with physical devices. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/Issues.md b/docs/dimensional-debris/src/content/docs/Issues.md new file mode 100644 index 0000000..9367574 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/Issues.md @@ -0,0 +1,329 @@ +--- +title: Issues +--- + +## Issues and Troubleshooting +### Common issues and how to fix them + +#### Introduction + +You know those computery things that make you facepalm and want to give up because you have no idea why it's happening to you, and all at 3AM running on no sleep? Yeah, I know I do, and I'll be referring to these god-forsaken moments as "gotchas". Because they gotcha. Then sprinkled on some sleep deprivation for good measure. + +This document contains numerous issues that you may encounter when using both this project and macOS itself - ranging from AutoPilot to GPU passthrough issues. This document is a better, more organised version of the old ``Gotchas.md`` file. + +> [!NOTE] +> This document will be updated frequently. + +*** + +#### Main Menu + +These are issues you may encounter when first running the project via the ``main.py`` script. + +
main.py: Permission denied
 + +**NOTE:** As of v0.9.8, files are packaged as executable by default, and do not require additional permission modifications. + +Awww, you little donkey. You forgot to make it executable. + +```sh +$ chmod +x ./main.py +``` + +*sigh*. I did say it was for noobs. Dammit. + +
+ +
Virtual machine detected, functionality may be limited
 + +Exactly what it says on the tin. However, it **is** just a warning. + +You can still access all aspects of the project, but they probably won't work unless you have nested virtualisation enabled, and even then, good luck with performance. + +If this message appears in error, and it is your host machine, please [submit an issue on GitHub](https://github.com/Coopydood/ultimate-macOS-KVM/issues/new), providing your system specifications in the issue. + +
+ +
Incompatible OS detected
 + +Yeaaaaah, no. Your little misadventure was just busted before it began. + +As of [v0.9.5](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-9-5.md), an OS platform check is performed when running this project, and may prevent you from running `main.py`. This simply means that *you aren't using Linux*. And, you *need* Linux, as pointed out [here](https://github.com/Coopydood/ultimate-macOS-KVM#oh-and-you-need-linux). + +This is because KVM - the premise of this whole project - is a part of the Linux kernel. + +If this message appears in error, and you *are* running a distrobution of Linux, please [submit an issue on GitHub](https://github.com/Coopydood/ultimate-macOS-KVM/issues/new), providing your system specifications in the issue. + +If you're **sure** this is an error, you can bypass this check with the `--skip-os-check` argument, like so: + +```sh +$ ./main.py --skip-os-check +``` + +> [!WARNING] +> Doing so with an unsupported OS may have unexpected consequences, and ones I am not prepared to take responsibility for. The check is implemented for a reason - although mostly to save you the disappointment. + +
+ +*** + +#### AutoPilot + +These are various issues you may encounter throughout the built-in AutoPilot tool. + +
AutoPilot can't create a virtual hard disk file
 + +You probably don't have ``qemu-tools`` installed. + +However, if the issue persists, you can try making the HDD file yourself: +```sh +$ qemu-img create -f qcow2 HDD.qcow2 G +``` + +then try running AutoPilot again. It will detect the disk file and ask if you want to use it. + +
+ +
AutoPilot exits silently during user questions
 + +This is likely due to an "extreme value" being entered. + +For example, if the question had menu answer options of ``1``, ``2``, ``3``, ``?``, and ``Q`` - but you entered ``4``, this would cause the input to get confused and simply *yeet*. + +Because my Python skillz are nothing short of terrible, extreme handling wasn't implemented until [v0.9.5](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-9-5.md), and even then it may not work fully. + +
+ +*** + +#### Installing macOS + +These are issues related to the macOS installation process. + +
macOS recovery: an internet connection is required
 + +Make sure your network adapter model is set correctly in your config file. You may want to try with the ``vmxnet3`` virtual network device. + +Also make sure that the virtual network is started. You can do this with + +```sh +$ sudo virsh net-start default +``` + +
+ +
macOS Ventura (13.X) fails to install or upgrade, with various errors
 + +This was a [known issue](https://github.com/Coopydood/ultimate-macOS-KVM/issues/10), and has been resolved: + +This issue does NOT affect users who changed their CPU model from the default. For example, if you manually changed your CPU model to ``host``, this does not affect you. + +**FOR NEW USERS:** as of [v0.9.6](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-9-6.md), this issue has been fixed, and new files generated with AutoPilot will use the new model by default, which can be used to install Ventura. + +**FOR EXISTING USERS:** for users of **v0.9.5** or earlier, you have a couple options: +*** +1. If you have an existing AutoPilot config that you have used for a while, with many customisations of your own, it may be best to just change the CPU model. Do this by finding the following line in your boot script: +```sh +CPU_MODEL="Penryn" +``` +and change it to +```sh +CPU_MODEL="Haswell-noTSX" +``` + +*** + +2. Generate a new AutoPilot config file. While this does mean you have to go through AutoPilot again, there are a number of benefits. Generating a new AP config ensures you have the latest structure updates, and the best compatibility with the rest of the project: + + - You can **keep your existing config file**, either by choosing a different name, or by backing up your old one when prompted + - You can **keep and use your existing virtual hard disk file**. When AP gets to the `Creating virtual hard disk` stage, you'll automatically be notified about the existing HDD file, and you'll have the option to use the file in the new config. + - Your **OpenCore boot image will be replaced**, but your old OpenCore image will **automatically get backed up to a timestamped folder, in the `boot` folder**. If you've made customisations to the OpenCore image, you can move the old one back into place after AP finishes. + - The **virtual NVRAM will be reset**, but this is safe. In [v0.9.2](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-9-2.md) and later, you can even select your screen resolution as an AutoPilot stage - meaning you won't lose any resolution changes you may have made. + +*** +~~While this is investigated, please do not try to install or upgrade to macOS Ventura, as this may be unrecoverable until resolved. Stick to **macOS Monterey (12)** or earlier for now.~~ + +~~The most stable tested OS is **macOS Big Sur (11)**.~~ + +~~If you'd like to help the investigation, any and all testing is greatly appreciated, and can be submitted as a comment to the issue linked above.~~ + +
+ +
No disks available during macOS installation
 + +If you're in macOS Recovery and trying to use the installer, you'll get to a screen asking you to select a disk. + +If this screen only shows "macOS Base System" (greyed out), then it simply means you have not formatted the virtual disk yet. + +This can be done by using **Disk Utility** from the macOS Recovery menu. + +Select the ``QEMU HARDDISK`` entry from the sidebar with the storage capacity corresponding to what you chose during AutoPilot - be careful not to erase the small OpenCore partition. + +When selected, click "Erase" from the centre-top header, and enter a name for the new disk; this can be whatever you want. The default is ``Untitled``, so you can be classy and call it ``Titled``, or if you want to emulate a real Mac, call it ``Macintosh HD``. It's up to you. + +For the filesystem, leave ``APFS`` as the selected option, unless you particularly want to use Mac OS Extended. + +Then, simply quit Disk Utility and return to the macOS installer. On the disk selection screen, your newly-formatted disk should appear as a selectable option. Click it, and then click ``Install``. Done! + +
+ +*** + +#### macOS Post-Install + +These are issues related to the macOS after it has been fully installed. + +
Very long boot time on macOS Ventura and later ("PCIEnumerationWaitTime is 900" etc.)
 + +There may be a bug present in the macOS verbose system that temporarily hangs the boot process for a very long time - sometimes upwards of 10 minutes in some cases. + +This can almost be classed as a red-herring - as most users would assume their system has crashed at this point - when in actual fact letting it sit will eventually get it to boot. + +**However, you can fix this boot time by removing the ``-v`` boot argument.** After disabling verbose boot (``-v``), boot times in my case went from >5 minutes to under 30 seconds. Wow! + + +
+ +
Black screen or reset after install when using AMD RX 5xxx / 6xxx (Navi) GPUs
 + +This is likely due to a missing boot argument required for display out on RX 5000 and RX 6000 series cards. + +You need to add the following boot argument to the OpenCore image: +``` +agdpmod=pikera +``` + + +As of [**v0.11.0**](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-11-0.md) and later, the OpenCore image can be patched automatically using the **AutoPatch** functionality included in the **macOS Boot Argument Editor** tool - located in ``Extras > macOS Boot Argument Editor``. + +Alternatively, such as on older versions, this can be done from within macOS using **OpenCore Configurator**. If you used the **VFIO-PCI Passthrough Assistant** to configure passthrough, you can use the generated ``-noPT.sh`` file to temporarily boot macOS without passthrough enabled - allowing you to make the necessary changes. + +
+ +
Kernel: Couldn't alloc class "AppleKeyStoreTest"
 + +Being stuck here after passing through a GPU on macOS Ventura and later may actually be deceptive. + +Either the system has in fact panicked, or **it may still be booting in the background**. No, really! + +If you're "stuck" at ``Couldn't alloc class "AppleKeyStoreTest"``, wait up to 5 minutes. There may be a bug present in the macOS verbose system that prevents any more output after a certain stage. + +**You can fix this boot time by removing the ``-v`` boot argument.** + +Found by @DomTrues. + +
+ +*** + +#### QEMU and virt-manager + +These are issues you may run into when using both QEMU scripts and virt-manager (virsh) domains. + +
qemu-system-x86_64: warning: Number of SMP cpus requested (X) exceeds the recommended cpus supported by KVM (X)
 + +This is caused by incorrect virtual CPU topology. You may have set an invalid number of virtual CPU cores and/or threads. + +Please read [this document](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/AutoPilot) on the wiki to learn what values you should use. + +
+ +
vfio 0000:00:00.0: failed to open /dev/vfio/X: Permission denied
 + +This is what happens when trying to run a script file that contains PCI passthrough as a regular user. + +Thankfully, this is of course an easy fix. You'll need to run the script as superuser; + +```sh +$ sudo ./boot.sh +``` +
+ +
Unknown PCI header type "127" (vendor reset bug)
 + +Sometimes, when stopping or resetting a virtual machine with an AMD GPU passed through, the "reset" mechanism used to detach the GPU from the virtual machine fails. + +This is due to a problem known as the **vendor reset bug**. It affects a large variety of AMD GPUs, and is a firmware-level flaw. + +Unfortunately, after seeing this message, the only way to use the GPU again with a VM (even the same one) is to restart the host entirely. Even this might be difficult, as the shutdown process may hang when trying to reset the GPU before power off. Make sure you save all your work, and allow as many system processes to exit as possible, and then hard-reset the host. + +Although annoying, it's pretty benign. You can install ``vendor-reset`` using the ``vendor-reset-dkms-git`` package, which will likely not eliminate the issue entirely, but prevents it happening as often. + +It's also worth noting that some cards are affected worse than others, so occurance of the issue may vary. + + +
+ +*** + +#### VFIO-PCI and Passthrough + +These are issues related to PCI device passthrough using VFIO-PCI. This includes GPU issues. + +
Black screen or reset on AMD RX 5xxx / 6xxx (Navi) GPUs +
 + +This is likely due to a missing boot argument required for display out on RX 5000 and RX 6000 series cards. + +You need to add the following boot argument to the OpenCore image: +``` +agdpmod=pikera +``` + + +As of [**v0.11.0**](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-11-0.md) and later, the OpenCore image can be patched automatically using the **AutoPatch** functionality included in the **macOS Boot Argument Editor** tool - located in ``Extras > macOS Boot Argument Editor``. + +Alternatively, such as on older versions, this can be done from within macOS using **OpenCore Configurator**. If you used the **VFIO-PCI Passthrough Assistant** to configure passthrough, you can use the generated ``-noPT.sh`` file to temporarily boot macOS without passthrough enabled - allowing you to make the necessary changes. + +
+ + +*** + +#### Miscellaneous + +Other issues related to the project or macOS that don't fit into any of the other categories. + +
Repository file integrity damaged
 + +When using AutoPilot, the restore tools suite, system checkers, or the built-in updater tool, you may encounter an error regarding repo file integrity. + +This indicates that critical files needed for the project to operate were not found when searched for by the running script. + +Please check that you have not moved or deleted core files, such as those in the ``resources`` folder. + +To repair the repo integrity, you may have to use the online-based restore tool, that can be accessed by typing ``X`` at the restore tools menu. + +
+ +
XML converstion tool crashes when converting AutoPilot script, or has incorrect values
 + +Even if the AutoPilot script **is** valid, it may still be incompatible. + +This is because the underlying structure of AP config files was changed in [v0.9.2](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-9-2.md), and the XML conversion tool looks for this structure. + +> [!WARNING] +> Therefore, any AutoPilot config files created using **v0.9.1 or earlier** should **NOT** be used with the XML conversion tool. + +Support for updating legacy AP files may come in the future, but for now it is recommended that you simply create a new AP config. **You can keep your data** - just have your existing ``HDD.qcow2`` file in the root ``ultimate-macOS-KVM`` folder, and when AutoPilot reaches the hard disk creation stage, you'll be given the option to use the existing HDD file. You can also skip the macOS image stage if macOS is already installed. + +
+ + + +
Who the hell is Eversiege?
 + +You may have seen the name ``Eversiege`` pop up throughout the project. Who is it you ask? + +[Ask him.](https://github.com/eversiege) + +It's not like I know. + +
+ +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/MainMenu.md b/docs/dimensional-debris/src/content/docs/MainMenu.md new file mode 100644 index 0000000..135c2a3 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/MainMenu.md @@ -0,0 +1,89 @@ +--- +title: Main Menu +--- + +## Main Menu +### main.py +This file acts as the project's main menu and should be used for all of your endeavors. + + + +This section will highlight each option and briefly explain what it does without going into detail. + +*** +## 1. AutoPilot +This is what I'd consider to be the "meat and potatoes" of the project - but that might be biased considering it's what took me the longest to make... +Anyway, AutoPilot is an advanced script designed to completely automate the generation of a fully valid QEMU boot script - customised to exactly your specifications. + +AutoPilot lets you configure the following: +* Script name +* Target OS +* CPU cores +* CPU threads +* CPU model +* CPU feature args +* Allocated RAM +* Hard disk +* Network adapter model +* MAC address +* Bootable macOS recovery image + +For more information on AutoPilot, see [this page](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/AutoPilot). + +*** + +## 2. Download macOS... + +Adapted from **vit9696**'s `fetch-macOS-v2.py` script, this option lets you easily select and download the base recovery image for your desired version of macOS. I've modified this script to work with this project specifically, but the changes are minor and all credit should go to vit9696 for their work on this script. + +The file downloaded is in the **.dmg** format, which for the purpose of booting a VM, is completely useless. So, I've adapted the script to automatically launch **dmg2img**, a small program that extracts Apple DMG files into **.img** files - which *can* be booted. + +It's also worth noting that the file downloaded is **not** the full installer image, but rather the relatively small **BaseSystem.dmg** used for macOS recovery. The BaseSystem file download is typically under 800 MB. To install macOS, you will need an internet connection - with the total download size from recovery itself often exceeding 10 GB. + +*** + +## 3. Compatibility checks... + +This menu contains a few scripts designed to automatically test your system configuration and check it for any issues that may prevent you from using features such as KVM itself or VFIO-PCI passthrough. Your installed GPU(s) can also be checked for compatibility with macOS from this menu too. + +*** + +## 4. Passthrough tools... + +Another menu that presents a list of useful tools that can assist in the preparation and configuration of VFIO-PCI passthrough of physical PCI devices, such as GPUs or audio cards. This menu also lets you start the **VFIO-PCI passthrough assistant** - an easy, guided way to get your system set up for successful passthrough. + + +*** + +## E. Extras... + +What it says on the tin, really. This menu contains loads of other goodies, such as the **XML Converter** - which lets you convert and import your AutoPilot scripts into XMLs for use with Virtual Machine Manager! + +You can also do other things here such as **resetting your OpenCore image**, or resetting **the entire repo** for those oopsie-whoopsie moments. + +For more information on Exras, see [this page](https://github.com/Coopydood/ultimate-macOS-KVM/wiki/Extras). + +*** + +## W. What's new? + +This option simply opens your current version's release changelog in your default browser. + +*** + +## U. Check for updates... + +This project has been designed to be updated and made better over time. + +As you use it to generate your personal files, having to re-clone the entire repo yourself while preserving your files would be a right pain in the backside. + +Therefore, there's an automated updater script built right-in that you can use to safely update in-place to newer versions of this project, without affecting any of your personal config files, virtual hard drives, or anything else not part of the project files. And, if an update dramatically changes directory structures from your current version, the updater automatically disables its in-place update mechanism to prevent data loss. + +Of course, if you're just testing the project, then a "clean install" is probably still preferable. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/OpenCore.md b/docs/dimensional-debris/src/content/docs/OpenCore.md new file mode 100644 index 0000000..36b5d4b --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/OpenCore.md @@ -0,0 +1,59 @@ +--- +title: OpenCore +--- + + +## OpenCore +### Important information about the included OpenCore image + +#### Introduction +This project contains several customised OpenCore bootloader disk images, modified from kholia's OSX-KVM repo. The images have been set up in a way that should work out-of-the-box without any user modification. + +However, due to this one-size-fits-all configuration shared among all users of the project, you might *want* to manually edit some things. + +The default OpenCore image included with **ultimate-macOS-KVM** presents the following system properties: + +- **Model**: Mac mini (2018) +- **Identifier**: Macmini8,1 +- **Processor**: Dual-Core Intel Core i7 @ 2.9GHz +- **Serial Number**: C07W10D9JYVX + +#### Do NOT sign in to your Apple ID yet! +But don't worry, you can after some light tinkering. + +The problem lies with the *serial number*. The default Mac serial number that comes with the OpenCore image included in this project is **C07W10D9JYVX**. While this *is* in the correct format for a Mac Mini 2018, it's likely going to be shared by several users. + +This becomes a problem when Apple IDs get involved. When you sign in to a Mac with your Apple ID, it becomes associated with it, via the serial number. When many people sign in to their unique Apple IDs on the same shared serial number- ...well, some folks at Apple likely begin to stroke their neckbeards. + +Basically, the serial number gets **busted**. Or, less dramatically - blacklisted. This means that any Apple ID that tries to sign into it will be flagged as compromised, prompting the user to perform a mandatory password change. Trust me, this is not a headache you want. + +So, in order to sign in to your own Apple ID safely, you need your *own* serial number. Ya dig? Read on. + +#### Getting your own serial number +Now that you understand the *"why"*, it's time to learn the *"how"*. + +> [!IMPORTANT] +> Unless you're booting macOS for the first time *with an already-modified OpenCore image containing a unique serial number*, you **should NOT sign in with your Apple ID during Setup Assistant under ANY CIRCUMSTANCES.** + +Create a "local" user account by skipping the Apple ID stage of the Setup Assistant. After you complete the Setup Assistant with a regular local account, you can continue. + +Now, check your serial number. Go to **Apple Menu > About this Mac** and look at the **Serial Number** entry. If your serial number is **C07W10D9JYVX**, you still have the shared default, and should change it. + +To do this, the easiest method is to use **OpenCore Configurator** from within the macOS VM. This can be obtained here: https://mackie100projects.altervista.org/download-opencore-configurator/ + +Open it, and in the menu bar, go to **Tools > Mount EFI**. A new window will pop up. There will be a couple of entries called "EFI". The one we want is the entry **without** "Preboot,Recovery,VM" etc. + +Click **Mount**, authenticate, and close the popup window. Then, on the menu bar, go to **File > Open**. From here, use the Finder popup window to navigate to **EFI > OC** and select **config.plist**. The main window should reopen with entries already populated. + +Now, down the side of the main window, click **PlatformInfo**, then along the tab bar at the top to **SMBIOS**. At the bottom of the page, there is a combo box (select list) to the right of "Check Coverage". Click it, and browse the list of Mac models until you find one that you want (or just choose the 2018 Mac mini again). + +The many fields on the page should now be populated with values, including the *serial number* at the top. Under the box, there should be a **Generate** button. Click that and make sure the new serial number is unique. When you've done this, go ahead and go to **File > Save**, and reboot the VM. + +Upon reboot, check the serial number again from the **About this Mac** window. If it has been changed - **congratulations**! You now have a unique serial number. This means you can safely log into your Apple ID, with the assurance no one else will use that serial number. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/PassthroughAssistant.md b/docs/dimensional-debris/src/content/docs/PassthroughAssistant.md new file mode 100644 index 0000000..d6be88a --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/PassthroughAssistant.md @@ -0,0 +1,120 @@ +--- +title: FPassthrough Assistant +--- + +## VFIO-PCI Passthrough Assistant +### Add physical PCI device passthrough with ease + +#### Introduction + +The *VFIO-PCI Passthrough Assistant* is an included utility script within the project. + +It can be found and run from the **Passthrough Tools** menu. + +This tool allows you to automatically add your stubbed VFIO-PCI devices to your existing AutoPilot script, and walks you through each step of the process, including automatically detecting devices, and formatting the custom QEMU arguments for your specific devices. + +*** + +#### Compatibility + +Before you begin this misadventure, you should ideally make sure that you and your system are ready. There is a built in check tool to assist you with this. + +*** + +## 🛑 STOP! + +#### This guide assumes you have fully set up your OS and devices for passthrough. + +You should return to this guide only when ALL of the following are complete: + +- Kernel is compatible and [set up to load the required modules]() +- Your OS is installed and booted in UEFI mode +- Your host supports IOMMU **and** you've [added the relevant kernel modules and parameters]() +- The devices you want to pass through are confined to their own [IOMMU groups]() +- The devices are bound to the ``vfio-pci`` kernel driver using the [VFIO kernel parameters]() + +Please see the [comprehensive passthrough guide]() for a full explanation of these tasks. + +*** + +## 1. Selecting devices + +Once the assistant successfully detects devices bound to the ``vfio-pci`` kernel driver, you will be presented with a menu displaying the total number of detected devices. + +IMAGE + +After continuing, a list of the detected devices will be shown under the ``AVAILABLE DEVICES`` heading. Each device will be assigned a number from ``1`` onwards. + +To select devices to pass through to your VM, type each device entry's corresponding number followed by ENTER. As you select devices, they will light up and move from under the ``AVAILABLE DEVICES`` heading to under the ``SELECTED DEVICES`` heading. + +To deselect a device, type its corresponding number again to move it back. + +Once you have selected the devices you want, type the word ``done`` and press ENTER. + +*** + +## 2. Confirm your selections + +After selecting your devices to pass through, you will be shown a summary screen allowing you to confirm your selections. The names of each device will be shown, along with a preview of the QEMU argument that will be generated for it. + +IMAGE + +To confirm your selections, type ``Y`` and press ENTER. If you'd like to go back, type ``N`` and press ENTER. + +*** + +## 3. Add arguments to boot script + +There are 3 options you can choose from after confirming your device selections: + +
    +
  1. Auto-detected script (recommended)
    2. +This is by far the easiest and most convenient option. If you generated your boot script using AutoPilot, the passthrough assistant will try to detect this automatically, and offer to add the new passthrough devices to this script for you. + +
  2. Manually selected script
    3. +If the passthrough assistant fails to automatically find an AutoPilot-generated boot script - or you want to add the devices to a different script - you can enter the path to the desired script file. It MUST have been generated by AutoPilot at some point - but does not have to be from the current installation or version of ULTMOS. + +
  3. Save to file
    4. +If you'd rather save the generated QEMU device arguments for a later time, you can do this too. All of the generated lines will be saved to a text file in the root of the repo directory. You can use this to copy and paste the lines into other non-AutoPilot scripts. +
+ +Select an option when prompted and press ENTER. The assistant will perform your chosen method. + +*** + +## Other features + +### If the assistant detects a GPU + +After confirming your device selections in step 2, you may receive another screen informing you that the assistant has detected one or more of your selections may be a GPU. + +Some GPUs require [specific VBIOS ROM files]() to be used with VFIO-PCI passthrough. The assistant allows you to enter the file path of a ROM file if you need it. The file is automatically copied to the ``roms`` directory in your repo folder. + +However, if your GPU does NOT need a ROM file (most likely), you can type ``skip`` and press ENTER to continue without one. + +
+ +### If the assistant offers boot patches + +Some devices are known to have issues or otherwise interfere with the macOS boot process - such as **AMD's Navi-based GPUs**. The passthrough assistant is designed to try and detect these devices, and offer automatic boot patching through integration with the [macOS Boot Argument Editor]() - if patches are available. + +If problematic devices are detected - and relevant patches are available - the assistant will offer you the chance to automatically patch your OpenCore image immediately to ensure a seamless passthrough experience. + +It *is* just an offer, and if you'd rather do it yourself later, you'll always have the option to skip. You can apply the same available patches at any time using the **macOS Boot Argument Editor**, found in the **Extras menu**. + +
+ +### If virtual input devices were removed + +After passing through devices that inhibit the operation of virtual input devices - such as the virtual mouse and keyboard emulation - the assistant will alert you of this and offer to run the **USB passthrough assistant**. + +This allows you to add physical input devices connected to your host, in order to interact with the virtual machine without the need for input emulation. + +As always, this is optional, and the USB passthrough assistant can be run at any time from the **passthrough tools menu**. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/RemoteDesktop.md b/docs/dimensional-debris/src/content/docs/RemoteDesktop.md new file mode 100644 index 0000000..5aa3d67 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/RemoteDesktop.md @@ -0,0 +1,91 @@ +--- +title: Remote Desktop +--- + + +## Remote Access and Desktop + +### Both to and from the guest + +#### Introduction + +Various remote access and remote desktop methods provide a way to interact with both your host OS and guest OS, *to and from* either side. This document will go over a couple of methods you can use, and which are best for specific scenarios you may find yourself in. Let's go! + +*** + +#### Access? Desktop? Wat?! + +First of all, I'll quickly define what I mean by "remote access" and "remote desktop". + +**Remote Access** refers to simply accessing the machine over the network remotely - such as Secure Shell (SSH) or a variety of filesharing methods. + +**Remote Desktop** refers to actually *viewing* what's being graphically displayed on the machine - through both physical and virtual display outputs. With this, you can also directly control the machine's mouse and keyboard inputs through your own, if permitted. + +*** + +#### Secure Shell (SSH) + +The quickest and most simple way to remote access into a machine is through SSH. + +SSH allows you to use a terminal emulator on a remote device - such as your phone - to directly execute commands on the target machine. It's essentially like opening a terminal window on your host machine, but displayed on another machine. + +It's especially useful for those with only a single GPU or display - or when passing through an entire USB controller - as you can start and stop virtual machines using commands remotely, even when your host OS is headless. + +| **What it's good for** | **What it isn't good for** | +|:---------------------------------------------:|:--------------------------:| +| Starting and stopping running VMs | File transfer | +| Editing config files through the command line | GUI applications | +| Rebooting your host if necessary | | + +*** + +#### Samba File Sharing (SMB) + +Samba is the most simple and diverse way to access and share files between a variety of OSes. + +You can use Samba to set up SMB shares, that can then be accessed from virtually any operating system, regardless of filesystem. For example, you can set up a share on your Linux host, and access it from within the macOS VM. It can even be set up as read-only if you prefer. + +This is really useful for sharing a unified fileset between your host and guest, or multiple guests. Being able to quickly grab a file from your downloads or a line of code from a project folder is very handy! + +| **What it's good for** | **What it isn't good for** | +|:---------------------------:|:--------------------------:| +| File transfer | Network congestion | +| Accessing files from any OS | Bandwidth | +| Wide compatibility | Bufferbloat | + +*** + +#### ShareMouse + +This is a cross-platform program that lets you share your mouse cursor between machines and OSes seamlessly. + +Many other tools also exist that have similar functionality. + +| **What it's good for** | **What it isn't good for** | +|:--------------------------:|:--------------------------:| +| Continuity | Low latency | +| Ease of use | Performance | +| Share the same USB devices | Stability | + +*** + +#### Virtual Network Computing (VNC) + +VNC is a widely-used and reliable remote desktop protocol. It provides cross-platform desktop viewing and control, and has support built in to several OSes, with virtually all OSes having both a VNC client and server application developed for it. + +VNC is reliable over local networks, and can be port forwarded to access remotely on sufficient internet connections. + +For example, macOS has a VNC server built into the OS. You can enable it in *System Preferences > Sharing > Remote Desktop*. + +| **What it's good for** | **What it isn't good for** | +|:----------------------:|:--------------------------:| +| Basic remote desktop | Intensive workloads | +| Reliability | Gaming | +| Compatibility | Resource usage | + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/SupportedGuests.md b/docs/dimensional-debris/src/content/docs/SupportedGuests.md new file mode 100644 index 0000000..bb3ccd7 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/SupportedGuests.md @@ -0,0 +1,88 @@ +--- +title: Supported Guests +--- + +## macOS + + + + + +

macOS Sonoma
14.5

+ +This project currently supports the latest version of macOS Sonoma, as well as every prior version down to macOS High Sierra. + +The option to use legacy versions is available, but no support will be provided and any issues you encounter are your own to solve!
+ +#### Supported + + +
macOS Ventura
+ +
macOS Monterey
+ +
macOS Big Sur
+ +
macOS Catalina
+ +
macOS Mojave
+ +
macOS High Sierra

+ +#### Pre-Release + + +
macOS Sequoia Beta

+ + +#### Legacy + + +
macOS Sierra
+ +
Mac OS X El Capitan
+ +
Mac OS X Yosemite
+ +
Mac OS X Mavericks
+ +
Mac OS X Mountain Lion
+ +
Mac OS X Lion
+ + + + + +
+
+ +## Feature Table + + +This table is a very **loose** representation of the current state of macOS versions and their support with ULTMOS / QEMU / KVM. It's more for reference and shouldn't be taken seriously. + +If you find something is wrongly marked, please feel free to update it. + +
+ +| | | | | | | | | | +|--------------------------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:---------:|:---------:| +| **AutoPilot** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| **Auto
Download** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✕ | +| **Online
Install** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| **Offline
Install** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| **QEMU
Script** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓¹ | ✓¹ | ✓¹ | +| **Virt
Manager** | ✓ | ✓ | ✓ | ✓ | ✓ | ?² | ?² | ?² | +| **GPU
Passthrough** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓¹ | ✓¹ | ✓¹ | +| **VirtIO
Networking** | ✕ | ✕ | ?³ | ✓ | ✓ | ✓ | ✓ | ✓ | +| **VirtIO
Storage** | ✕ | ✕ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + + +¹ If trying to boot macOS Ventura and later with GPU passthrough, you may need to do so using Virtual Machine Manager. The QEMU script may have issues with GPU passthrough. + +² macOS Ventura and later have been known to have issues booting *without* GPU passthrough in Virtual Machine Manager. + +³ I have no idea whether or not VirtIO networking works on macOS Catalina. + diff --git a/docs/dimensional-debris/src/content/docs/SupportedHosts.md b/docs/dimensional-debris/src/content/docs/SupportedHosts.md new file mode 100644 index 0000000..ad2f24c --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/SupportedHosts.md @@ -0,0 +1,67 @@ +--- +title: Supported Hosts +--- + +## Host OSes + +There are many, *many* distros of Linux to choose from. While theoretically universal, ULTMOS has been tested on several mainstream distros. These are listed below with links for your convenience. + +> [!NOTE] +> This is NOT an exhaustive list, and simply a recommended selection. You are always free to use any distro you like, and don't worry - issues / reports **will always be investigated regardless of your distro or if it's listed here!** + +#### Recommended + + + + +

Arch Linux
Arch Linux Contributors  •  Open Website... ⎋

+ +This is an advanced distro that is known for its no-nonsense approach to Linux. It does not come with a graphical desktop environment by default, making it a good choice for those who want a minimal system to run KVM on. ULTMOS was developed on this distro, and so compatibility with it is fully guaranteed. + +>[!CAUTION] +> Arch Linux is NOT recommended for new users, but for those already comfortable with Linux. When requesting support or reporting issues on this distro, you will be expected to have a fully working OS install. +
+
+ + + + +

EndeavourOS
EndeavourOS Team  •  Open Website... ⎋

+ +A more user-friendly approach to an Arch-based system. ULTMOS was developed primarily on Arch Linux, so for almost-guaranteed compatibility - an Arch-based distro is recommended.

+ + + + +

Linux Mint
Linux Mint Team  •  Open Website... ⎋

+ +The recommended option for new users; especially those who are accustomed to Windows. Linux Mint is built on an Ubuntu / Debian foundation. ULTMOS has been tested on Linux Mint.

+ + + + +

Zorin OS
Zorin OS Team  •  Open Website... ⎋

+ +This is another very user-friendly distro based on Ubuntu. Similar to Linux Mint, it is aimed at users of Windows by providing a simple but stylish design, that can be customised to look similar to other OSes. +
+
+ + + + +

Ubuntu
Canonical  •  Open Website... ⎋

+ +The most well-known Linux distro, popular for its application support and ease of use. Also forms the base framework for many other distros, such as Linux Mint. + +>[!WARNING] +> Ubuntu contains an application distribution method known as "Snap". These "Snap packages" are NOT compatible with ULTMOS, and you will lose technical support when submitting issues or bug reports if you install any dependencies as Snap packages. +
+
+ + + + +

Fedora
The Fedora Project  •  Open Website... ⎋

+ +A popular Linux distro developed by The Fedora Project. Several users have reported success using ULTMOS on Fedora. +
\ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/UsefulLinks.md b/docs/dimensional-debris/src/content/docs/UsefulLinks.md new file mode 100644 index 0000000..9a00e5c --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/UsefulLinks.md @@ -0,0 +1,23 @@ +--- +title: Useful Links +--- + +## Useful Links + +Here are some external links to other resources that you might find useful. + +- **[OSX-KVM](https://github.com/kholia/OSX-KVM)** 》 The original basis of this project, providing many resources for running macOS under KVM. +- **[Dortania's OpenCore Guide](https://dortania.github.io/OpenCore-Install-Guide/)** 》 An extensive website of documentation on Hackintosh systems as a whole, useful for troubleshooting issues on both physical and virtual machines. +- **[GPU Buyer's Guide](https://dortania.github.io/GPU-Buyers-Guide/)** 》 An excellent write up on Dortania's website to help you make informed GPU buying decisions for maximum success rates. This is the primary source of data used in the *GPU compatibility checker* script included in ULTMOS. +- **[LegacyOSXKVM](https://github.com/royalgraphx/LegacyOSXKVM)** 》 Documentation and resources on running legacy OS X versions. Legacy support in ULTMOS is based on this project. +- **[OpenCore Configurator](https://mackie100projects.altervista.org/download-opencore-configurator/)** 》 Download page for OCC, an application used to edit OpenCore configs from within macOS. + +> [!WARNING] +> These links and their contents are not authored, monitored, or maintained by Coopydood, and are not affiliated as such. They are provided for convenience purposes only. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/XMLConverter.md b/docs/dimensional-debris/src/content/docs/XMLConverter.md new file mode 100644 index 0000000..ad1913b --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/XMLConverter.md @@ -0,0 +1,115 @@ +--- +title: XML Conversion Tool +--- + +## XML Conversion Tool +### Convert and import AutoPilot boot scripts + +#### Introduction +The **XML Conversion Tool** is an included utility script within the project. + +It can be found and run from the **Extras** menu. + +This tool allows you to convert existing **AutoPilot-generated boot script files** into **XML domain files**, that can then be imported into the **Virtual Machine Manager (virt-manager)** GUI, for more user-friendly access. + +*** + +> [!WARNING] +> As of **[v0.9.2](https://github.com/Coopydood/ultimate-macOS-KVM/blob/main/docs/changelogs/v0-9-2.md)**, the base structure of AutoPilot boot scripts has been changed. +> +> Therefore, users with AutoPilot boot scripts generated using a version of **v0.9.1** or earlier should __**NOT**__ use the XML Conversion Tool with these scripts **UNLESS ALL** the following applies: +>- You're using v0.9.7 or later +>- The script is in the root `ultimate-macOS-KVM` directory +>- The matching AutoPilot blob files for the script are intact +>- The XML Conversion Tool is able to autodetect your script +> +>This is because as of v0.9.7, the XML Conversion Tool can now work using blobs - created when running AutoPilot. However, this only works when the blobs are still intact from the AP run that created your config file. They may be in the `stale` folder. If this is the case, move them to the parent `blobs` folder first. +> +>No support will be provided, and no testing has been conducted into the effects of using incompatible scripts. +> +>For the newest upstream boot script patches, you can *create a new AutoPilot config*, while preserving your existing hard disk file. +*** + + + +When first running the tool, you'll be given two options: + +**1. Convert AutoPilot config to XML** + +**2. Import XML file** + +This document will explain what each option does. + +*** +#### Convert AutoPilot config to XML + +For most people, this will be the only function needed in this tool. + +> [!IMPORTANT] +> If your AutoPilot boot script was created using a project version of v0.9.1 or earlier, you **MUST** read the compatibility warning above, as you probably can't use this unless several stars align. + +However, if your AutoPilot script was created using v0.9.2 or later, you can continue. + +Select `1. Convert AutoPilot config to XML`. + +The XML Conversion Tool does a quick scan of the root `ultimate-macOS-KVM` folder. If it finds a valid AutoPilot boot script, it will ask if you'd like to use the file it automatically detected. For most, this is likely the file you want. However, if you've moved your AutoPilot script file elsewhere, or have since renamed it, etc. - then you'll be asked to provide the path to a valid AutoPilot file. + +For example: +``` +/users/ULTMOS/Documents/Scripts/myBootScript.sh +``` +> [!WARNING] +> File paths with whitespace are not supported at this time. + +Hit the ENTER key. The tool will then scan the file selected and verify that it's a valid AutoPilot script. + +Then, when verified, make sure the correct file is listed, and select `1. Convert file to XML and import` from the option menu. + +The conversion process will now begin. This may take a few moments. The output XML file will be saved to the same directory and with the same name as the source script. So, for example: + +If you converted a script +``` +/users/ULTMOS/Documents/Scripts/myBootScript.sh +``` +the converted XML file would output to +``` +/users/ULTMOS/Documents/Scripts/myBootScript.xml +``` + +Your original script with the `.sh` extension is kept, and will not be removed after conversion. + +When conversion is complete, you'll be prompted to import your new XML file using `virsh`. See more in the section below. +*** +#### Import XML file + +Whether this was skipped during conversion, or you simply have an existing XML you'd like to import - this option helps you define a domain XML file with virsh. + +You'll be asked to select a valid `.xml` file. This must be in the correct **virsh domain** format, usually looking similar to this: + +```xml + + ultmos-130 + macOS 13.0 (ultimate-macOS-KVM) + macOS 13.0 + ... + + + + + + + +``` + +> [!NOTE] +> It does **NOT** have to have been created by ultimate-macOS-KVM. This function is designed to work with **ANY** domain XML file originating from anywhere. + +> [!NOTE] +> You will not be asked to select an XML file if you have just used the conversion function. The newly-converted file will be used automatically. + +*** + + + +Written and maintained by **Coopydood**. +
You can [contribute](https://github.com/Coopydood/ultimate-macOS-KVM/new/dev/docs) to documentation, too! \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-10-0.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-0.md new file mode 100644 index 0000000..9f17b5d --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-0.md @@ -0,0 +1,34 @@ +--- +title: v0.10.0 +parent: Changelogs + +--- + +## v0.10.0 + +### Moderate update • 05/10/2023 + +This update includes the following features / fixes / changes: + +- WIP macOS Sonoma (14) support +- Experimental support for legacy OS X versions (10.7 - 10.12) +- @DomTrues added OpenCore Configuration Assistant +- @eversiege added initial web landing page +- User-generated boot scripts can now be run outside of the repo folder +- Updated default CPU model for better compatibility +- AutoPilot now selects appropriate CPU model based on target OS +- Support for passthrough devices in Discord presence +- Base config fixes and improvements +- Fixed an issue where the VNC server IP would be replaced by the version number +- XML conversion tool fixes +- OpenCore image is no longer attached as readonly by default +- CPU model is now displayed during script verbose output +- *the marines are after me help* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-10-1.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-1.md new file mode 100644 index 0000000..3aa1095 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-1.md @@ -0,0 +1,31 @@ +--- +title: v0.10.1 +parent: Changelogs + +--- + +## v0.10.1 + +### Minor update • 07/10/2023 + +This update includes the following features / fixes / changes: + +- Added Discord rich presence to AutoPilot +- Changed wording of XML stage in AutoPilot flow +- Fixed an issue where the XML converter would inject incorrect CPU threads +- Fixed an issue where the XML converter would fail to import a converted AutoPilot script using 1 CPU thread (@DomTrues) +- Fixed an issue where XML debug info would not be injected during AP flow +- Fixed an issue where the working directory would be logged incorrectly +- XML converter now uses the macOS friendly name for domain titles +- XML converter will now disable the default VGA device if passthrough is detected +- Hard disk files generated by AutoPilot are now calibrated to hit the absolute target size after formatting from within macOS +- AutoPilot navigation legibility improvements +- *it works on my machine!* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-10-2.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-2.md new file mode 100644 index 0000000..ebdfaf6 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-2.md @@ -0,0 +1,36 @@ +--- +title: v0.10.2 +parent: Changelogs + +--- + +## v0.10.2 + +### Minor update • 19/10/2023 + +This update includes the following features / fixes / changes: + +- Added Boot Argument Editor +- Added argument support to @DomTrues' OpenCore Modification Assistant +- Re-add experimental macOS Sonoma support +- XML converter now correctly titles domains on legacy OS X versions +- Better invalid file handling in XML converter +- AutoPilot rich presence bug fixes +- Domain title XML converter patch applied to AutoPilot XML flow +- Preliminary support for APC blob read method in AutoPilot XML flow +- Critical patch applied for repo update utility +- Fixed an issue where Discord rich presence wouldn't launch in directory paths with spaces +- Fixed an issue where the ``--disable-logging`` argument would crash the script +- Minor readme changes (@eversiege) +- *don't you just hate "couldn't alloc class "AppleKeyStoreTest"*? + +To see individual code changes, visit the project's commits page at + +> [!WARNING] +> The built-in repo update utility cannot upgrade previous versions of the project to this release automatically. This functionality has been disabled to protect your existing repo data. You must upgrade to this release manually. + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-10-3.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-3.md new file mode 100644 index 0000000..d4254ca --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-3.md @@ -0,0 +1,26 @@ +--- +title: v0.10.3 +parent: Changelogs + +--- + +## v0.10.3 + +### Minor update • 14/11/2023 + +This update includes the following features / fixes / changes: + +- Full macOS Sonoma support +- Standalone macOS download script now supports macOS Sonoma +- New global markdown design specifications including block flairs +- Changelogs now support showing release-specific warnings and info +- Changelogs now display an info panel if a release has multiple contributors +- Fixed an issue where an incompatible update would show the wrong options +- Post-update and up-to-date screens in the repo updater now show a menu if run as part of a menu flow +- Readme formatting identity crisis +- *i genuinely have a love-hate relationship with the repo update script* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-10-4.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-4.md new file mode 100644 index 0000000..da13096 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-4.md @@ -0,0 +1,30 @@ +--- +title: v0.10.4 +parent: Changelogs + +--- + +## v0.10.4 + +### Minor update • 30/11/2023 + +This update includes the following features / fixes / changes: + +- Fixed an issue where macOS 11.0 and later might get marked as OS X +- Fixed XML converter title naming +- Log file location is now included on AutoPilot completion screen +- Hard disk modifications are now preserved when converting to XML +- New HDD file pathing mechanism +- Added the ability to select an existing HDD file in AutoPilot setup +- Added support for existing HDD files in XML converter +- Feature level system for compatibility adaptability +- Removed redundant (and potentially problematic) watchdog entry from base XML (@fishermedders) +- *macOS macOS macOS macOS Title (ULTMOS)* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-10-5.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-5.md new file mode 100644 index 0000000..750db73 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-10-5.md @@ -0,0 +1,27 @@ +--- +title: v0.10.5 +parent: Changelogs + +--- + +## v0.10.5 + +### Minor update • 02/12/2023 + +This update includes the following features / fixes / changes: + +- Added the ability to select the virtual disk type in AutoPilot +- BaseSystem attachment state is now honoured when converting to XML +- Added support for disk types to XML converter +- XML converter blob-based array initialisation can now be force-disabled with ``--no-blobs`` +- Fixed an issue where selecting macOS Ventura would download macOS Sonoma +- Fixed AutoPilot crash on completion screen if logging was disabled +- Fixed extreme value handling for existing hard disk paths in AutoPilot +- Fixed the displayed domain name on XML import success screen +- Minor wording changes in AutoPilot +- *GPU having an identity crisis be like `AMD ATI Radeon RX 5600 OEM/5600 XT / 5700/5700 XT`* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-11-0.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-0.md new file mode 100644 index 0000000..eebe2a3 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-0.md @@ -0,0 +1,46 @@ +--- +title: v0.11.0 +parent: Changelogs + +--- + +## v0.11.0 + +### Major update • 15/01/2024 + +This update includes the following features / fixes / changes: + +- Added USB passthrough assistant (@Hyperchromiac) +- Added the ability to use physical disks during AutoPilot +- Added support for physical disks to XML converter +- Added support for USB passthrough to XML converter +- Added Barrier installer (for use in macOS guest) +- Added experimental ``--targetBranch`` argument to updater +- VPTA will automatically offer relevant boot patches if needed +- Using VPTA to passthrough a GPU now offers the USB assistant +- Changed the default macOS version to macOS Monterey (12) +- OpenCore image patch rollup + disable secboot +- Generated scripts now display macOS version in the verbose panel +- Major UI change to device ID presentation across the project +- Full menu redesign throughout the project +- VFIO-PCI passthrough assistant overhaul with rich device selection (@Hyperchromiac) +- Existing OVMF variable file is no longer replaced by passthrough variant +- macOS Boot Argument Editor now supports AutoPatch CLI arguments +- Removed redundant passthrough tools menu shortcut from extras menu +- Removed macOS Sonoma experimental tag +- Removed VM-check from Extras menu for better performance +- Decreased storage size footprint of the project +- Fixed HDD generation size offset on macOS Ventura and later +- Fixed some issues relating to long boot times on macOS Ventura and later +- Fixed an issue where virtual NVMe drives would break when converting to XML +- Fixed an issue where macOS Boot Argument editor wouldn't unmount the OC image +- Minor README design changes +- *oh my god I can finally stage ALL my changes!!1!* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-11-1.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-1.md new file mode 100644 index 0000000..77babc0 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-1.md @@ -0,0 +1,27 @@ +--- +title: v0.11.1 +parent: Changelogs + +--- + +## v0.11.1 + +### Minor update • 23/02/2024 + +This update includes the following features / fixes / changes: + +- Discord rich presence now shows number of passthrough devices +- Fairly large documentation update +- Changed the way the XML converter interprets the VM name +- AutoPilot now hands off entire XML conversion to XMLC, rather than integrated ([#70](https://github.com/Coopydood/ultimate-macOS-KVM/issues/70) by [@dvdmuckle](https://github.com/dvdmuckle)) +- Fixed an issue where AutoPilot would crash with a TypeError ([#70](https://github.com/Coopydood/ultimate-macOS-KVM/issues/70)) +- Fixed an issue where XMLC may try to import the XML twice ([#70](https://github.com/Coopydood/ultimate-macOS-KVM/issues/70)) +- Fixed capitalisation in Extras menu +- AutoPilot summary main menu keybind updated in line with other menus +- Extremely long boot time on macOS Ventura and later can be fixed by removing the ``-v`` boot argument +- *invalid literal; "``SussyMac``"* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-11-2.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-2.md new file mode 100644 index 0000000..8f7df3a --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-2.md @@ -0,0 +1,24 @@ +--- +title: v0.11.2 +parent: Changelogs + +--- + +## v0.11.2 + +### Minor update • 03/04/2024 + +This update includes the following features / fixes / changes: + +- Fixed Sonoma 14.4 support in base config and AutoPilot (@jim-p) (#78 by @johanhenselmans) +- Fixed repo update utility branch targeting (#77 by @adil192) +- Changed the way the repo update utility fetches updates +- Added experimental support for displaying live, realtime notices of non-version-specific issues throughout AutoPilot +- Restyling of log file entries +- Support for debug lines in log files +- *macOS S**onomyusbdoesntwork** 14.4* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-11-3.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-3.md new file mode 100644 index 0000000..3bf0a48 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-11-3.md @@ -0,0 +1,29 @@ +--- +title: v0.11.3 +parent: Changelogs + +--- + +## v0.11.3 + +### Minor update • 28/04/2024 + +This update includes the following features / fixes / changes: + +- Added options for booting without passthrough or USB to main menu, if applicable +- Added progress bars for AutoPilot stages +- Added a progress bar when downloading macOS with AutoPilot or standalone script +- Added a splash screen on program exit +- Updated the progress bar style in system check scripts +- Changed the colour of grey used throughout the project for better contrast +- Fixed logging of BaseSystem check in AutoPilot flow +- Fixed the BaseSystem integrity check in AutoPilot +- Fixed the infinite error loop on incompatible OS detection +- Fixed an issue where the OVMF EFI shell would load after applying Sonoma 14.4 patch +- Fixed an issue where AutoPilot menu flow would get trapped after screen resolution stage when custom resolutions are unsupported +- *now that is a hot looking progress bar innit* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-12-0.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-0.md new file mode 100644 index 0000000..ca865b6 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-0.md @@ -0,0 +1,35 @@ +--- +title: v0.12.0 +parent: Changelogs + +--- + +## v0.12.0 + +### Major update • 11/06/2024 + +This update includes the following features / fixes / changes: + +- Added GenSMBIOS integration; support for automatic SMBIOS and serial number generation (suggestion by [@chxdr](https://github.com/chxdr)) +- Added an ULTMOS splash screen on VMs +- Added a system profile debug tool to assist with issues +- Support for more Discord rich presence customisation +- Updated OVMF files +- The repo update utility now searches the current branch for updates by default +- Implemented a possible fix for random EFI shell boots +- Made several changes to the base config +- Patched the included restore tools to work with modern repo versions +- Updated XMLC menu header design +- Minor AutoPilot UI changes +- Fixed an issue where AutoPilot would fail when using several legacy OS X versions +- Fixed name appearance on boot script startup message +- Fixed an issue where the update utility would not honour CLI arguments +- Fixed a Python launch command in the main menu +- Re-positioned progress bar UI layout +- Bundled libraries and begin transition to class files +- *everyone should have a BIOS splash screen that sexy* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-12-1.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-1.md new file mode 100644 index 0000000..5341b08 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-1.md @@ -0,0 +1,28 @@ +--- +title: v0.12.1 +parent: Changelogs + +--- + +## v0.12.1 + +### Minor update • 20/06/2024 + +This update includes the following features / fixes / changes: + +- Preliminary macOS Sequoia beta support +- Added macOS Sequoia beta support to Discord rich presence +- Added temporary download link for macOS Sequoia beta BaseSystem to readme header notification (Button design by @eversiege) +- Added a dialog allowing the user to automatically have the BaseSystem removed once a completed install is detected +- Fixed an issue where the OpenCore restore tool would fail +- Fixed an issue where the XML converter would not convert physical disks properly +- The BaseSystem is no longer included in the base domain XML file; it is now added on detection +- *macOS Sequhuehuehuehueio* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-12-2.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-2.md new file mode 100644 index 0000000..7812ed7 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-2.md @@ -0,0 +1,28 @@ +--- +title: v0.12.2 +parent: Changelogs + +--- + +## v0.12.2 + +### Minor update • 16/07/2024 + +This update includes the following features / fixes / changes: + +- Added a built-in fix for macOS High Sierra recovery server issue (@LuboGD)(#92) +- Fixed an issue where AutoPilot download flow was blocked for macOS 10.XX versions +- Fixed an issue where users could bypass the disallowed beta download option +- Documentation updates +- *I'm totally higher than macOS 10.13, man!* + +To see individual code changes, visit the project's commits page at + +> [!IMPORTANT] +> This update was re-released on **27/07/2024** to include important fixes. + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-12-3.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-3.md new file mode 100644 index 0000000..0893d7c --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-3.md @@ -0,0 +1,25 @@ +--- +title: v0.12.3 +parent: Changelogs + +--- + +## v0.12.3 + +### Minor update • 15/09/2024 + +This update includes the following features / fixes / changes: + +- Implemented a fix for the "config.plist not found" issue in macOS Boot Argument Editor (@kayon and @eversiege) +- Updated the styling of the stage titles in AutoPilot +- Add small warning about CPU threads in AutoPilot +- Changed the wording of some AutoPilot stage descriptions +- *The fix was literally to make it sleep more?!?1?* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> This release has multiple authors. Attributions for contributor changes are included in relevant lines above. + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-12-4.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-4.md new file mode 100644 index 0000000..269324f --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-12-4.md @@ -0,0 +1,23 @@ +--- +title: v0.12.4 +parent: Changelogs + +--- + +## v0.12.4 + +### Minor update • 19/09/2024 + +This update includes the following features / fixes / changes: + +- macOS Sequoia support +- Added automatic recovery download support in AutoPilot for macOS Sequoia +- Updated downloader scripts to support macOS Sequoia +- Prepare for major "NRS" update +- Remove local screenshots folder +- *do you think Mac-937A206F2EE63C01 would be a catchy nickname?* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-7-11.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-7-11.md new file mode 100644 index 0000000..5c025e4 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-7-11.md @@ -0,0 +1,19 @@ +--- +title: v0.7.11 +parent: Changelogs +--- + +## v0.7.11 +### Minor update • 25/01/2023 + +This update includes the following features / fixes / changes: + +- Fixed an issue where AutoPilot would fail to verify the creation of the virtual hard disk file and terminate +- AutoPilot variables now correctly flush after a fatal error +- Changed the AP automatic network device selection method +- Fixed an issue where the wrong OpenCore image would be used on the target OS + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-8-0.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-0.md new file mode 100644 index 0000000..2b7b503 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-0.md @@ -0,0 +1,19 @@ +--- +title: v0.8.0 +parent: Changelogs +--- + +## v0.8.0 +### Moderate update • 27/01/2023 + +This update includes the following features / fixes / changes: + +- VFIO-PCI passthrough assistant now works and can successfully append valid passthrough arguments to an AutoPilot-generated config script +- Updates can now be downloaded manually using the updater +- Patched updater to support 0.X versions +- Fixed an issue where the updater may detect a public build as pre-release + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-8-1.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-1.md new file mode 100644 index 0000000..adb5232 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-1.md @@ -0,0 +1,22 @@ +--- +title: v0.8.1 +parent: Changelogs + +--- + +## v0.8.1 +### Minor update • 28/01/2023 + +This update includes the following features / fixes / changes: + +- Added a MAC address selection and generation stage to AutoPilot +- Added variable to base config to support user AP MAC address selection +- Fixed OVMF compatibility issues with legacy project versions +- Fixed an issue in VFIO-PCI passthrough assistant where OVMF files would not be replaced after getting dirty +- Added optional disabled VNC port to base config +- Minor changes to the appearance of the extras menu + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-8-2.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-2.md new file mode 100644 index 0000000..f568c41 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-2.md @@ -0,0 +1,18 @@ +--- +title: v0.8.2 +parent: Changelogs + +--- + +## v0.8.2 +### Minor update • 10/03/2023 + +This update includes the following features / fixes / changes: + +- Added (for now?) internal tools to check both basic KVM and full VFIO-passthrough readiness +- These tools can be found in the ``/scripts/extras/`` folder. + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-8-3.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-3.md new file mode 100644 index 0000000..1712e69 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-3.md @@ -0,0 +1,25 @@ +--- +title: v0.8.3 +parent: Changelogs + +--- + +## v0.8.3 +### Minor update • 12/04/2023 + +This update includes the following features / fixes / changes: + +- Fixed some spelling mistakes in AutoPilot +- Fixed a critical issue where AutoPilot would fail to function on new repo clones +- Main menu now auto-detects valid AutoPilot config files and adds boot entry to menu +- Optimised the scope of first-time permission fixes +- Changed the structure of clean OVMF files +- Patched scripts with OVMF replacement routines to work with new structure +- Added the "Restore Tools" menu, accessed via the Extras menu +- Added several restoration scripts to aid easy automatic troubleshooting +- Reorganisation of the extras menu entries, including support for Restore Tools + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-8-4.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-4.md new file mode 100644 index 0000000..0111ca6 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-4.md @@ -0,0 +1,19 @@ +--- +title: v0.8.4 +parent: Changelogs + +--- + +## v0.8.4 +### Minor update • 13/04/2023 + +This update includes the following features / fixes / changes: + +- Added local and online restoration tools to Restore Tools menu +- Fixed menu B/F flow +- Fixed a minor text bug when viewing the Extras menu in a VM + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-8-5.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-5.md new file mode 100644 index 0000000..1466085 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-5.md @@ -0,0 +1,20 @@ +--- +title: v0.8.5 +parent: Changelogs + +--- + +## v0.8.5 +### Minor update • 13/04/2023 + +This update includes the following features / fixes / changes: + +- Original script versions from initial user clone are now backed up on first run +- Local restoration now includes core scripts +- Fixed an issue with permissions not being set correctly +- Truncated wording in restore scripts + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-8-6.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-6.md new file mode 100644 index 0000000..31e382f --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-8-6.md @@ -0,0 +1,21 @@ +--- +title: v0.8.6 +parent: Changelogs + +--- + +## v0.8.6 +### Minor update • 18/04/2023 + +This update includes the following features / fixes / changes: + +- Changed the way non-delta updates are flagged and dealt with +- Fixed an issue preventing the integrity check on some restore tool sessions +- The local restore tool will now warn if version differences could cause downgrade +- The local backup store is now flushed after a full restore with obliterator +- Minor wording changes to menus and readme + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-0.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-0.md new file mode 100644 index 0000000..8e24cbb --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-0.md @@ -0,0 +1,34 @@ +--- +title: v0.9.0 +parent: Changelogs + +--- + +## v0.9.0 +### Moderate update • 17/05/2023 + +This update includes the following features / fixes / changes: + +- Complete reorganisation of the menu flow +- `setup.py` is now `main.py` +- If updating, your old `setup.py` file will be replaced +- Added the System Compatibility Tools menu +- Added KVM system checker +- Added VFIO-PCI passthrough readiness checker +- Added a dedicated menu for VFIO-PCI / passthrough-related tools +- Added more variables to the included baseConfig for AutoPilot +- Added some screenshots to the docs folder +- Fixed styling of GPU compatibility checker script +- Fixed styling of macOS image downloader script +- Fixed integrity check on vNVRAM reset tool +- Fixed restoration process on vNVRAM reset tool +- Removed shameless plugs in GPU compatibilty checker +- Internal debug script updates +- Minor restructure of script files +- Minor wording changes to readme, including to reflect script renaming +- It's 2AM and I am going to sleep, goodnight changelog lurker + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-1.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-1.md new file mode 100644 index 0000000..6da6c30 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-1.md @@ -0,0 +1,20 @@ +--- +title: v0.9.1 +parent: Changelogs + +--- + +## v0.9.1 +### Minor update • 29/05/2023 + +This update includes the following features / fixes / changes: + +- Large overhaul to the repo update utility, including many new functions +- Added a quick-access "What's new?" option to main menu to view latest changelog +- Minor compatibility changes and better post-upgrade structure conversion +- Slightly less sleep deprived than I was when making v0.9.0 + +To see individual code changes, visit the project's commits page at https://github.com/Coopydood/ultimate-macOS-KVM/commits/main + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-2.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-2.md new file mode 100644 index 0000000..4b50fd2 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-2.md @@ -0,0 +1,29 @@ +--- +title: v0.9.2 +parent: Changelogs + +--- + +## v0.9.2 + +### Minor update • 13/07/2023 + +This update includes the following features / fixes / changes: + +- Added a screen resolution option stage to AutoPilot +- Updated base config to support user screen resolution +- Better config timestamping +- Added an XHCI USB controller to the base config for USB 3.1 support +- Tidied up the base config layout and marked areas of user concern +- Updated macOS downloader script with vit9696's updates +- OpenCore image update rollup; updated kexts and bootcode +- Removed support for legacy 0.8.x versions, directory structure change +- Fixed an issue where AutoPilot would not accept custom values if project was newly cloned +- Fixed an issue preventing the script backup store on certain upgraded repos +- Added new bugs, according to Eversiege (please report!?) +- *yawns* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-3.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-3.md new file mode 100644 index 0000000..5f9f234 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-3.md @@ -0,0 +1,29 @@ +--- +title: v0.9.3 +parent: Changelogs + +--- + +## v0.9.3 + +### Minor update • 06/08/2023 + +This update includes the following features / fixes / changes: + +- XML Conversion tool; AutoPilot to XML for use with virt-manager +- Added more documentation +- Added an option to quickly report an issue on GitHub to the extras menu +- Minor UI improvements +- Fixed some menu flows +- Fixed an issue where dragging an AutoPilot config file into the VFIO-PCI Passthrough assistant would show as invalid +- Fixed an issue where VFIO-PCI Passthrough assistant would crash trying to write to a manually-selected file +- Fixed an issue where the wrong OVMF variable file would be copied during AutoPilot +- Changed the way that post-live AutoPilot blobs are stored +- Included wiki documents as offline files included in the `docs` folder +- Soothed Eversiege's "inner perfectionist" +- *falls asleep on keyboarddddddddd...* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-4.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-4.md new file mode 100644 index 0000000..5368587 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-4.md @@ -0,0 +1,28 @@ +--- +title: v0.9.4 +parent: Changelogs + +--- + +## v0.9.4 + +### Minor update • 11/08/2023 + +This update includes the following features / fixes / changes: + +- Smarter GPU checker +- Larger GPU support database +- Minor XML converter patches +- Changed default domain XML from network bridge to NAT +- Begin work on backup and restore assistant +- AutoPilot now seamlessly downloads the correct base system as part of the automated flow +- Fixed an issue where AutoPilot would copy all *.fd resources files +- Fixed an issue where AutoPilot would close unexpectedly +- AutoPilot no longer makes a junk CDN control file +- Begin acknowledging macOS Sonoma's existence in scripts +- *thump* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-5.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-5.md new file mode 100644 index 0000000..4d41db3 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-5.md @@ -0,0 +1,31 @@ +--- +title: v0.9.5 +parent: Changelogs + +--- + +## v0.9.5 + +### Minor update • 14/08/2023 + +This update includes the following features / fixes / changes: + +- Added option to generate XML file as part of AutoPilot flow +- AutoPilot stage flow updated to support XML file generation +- AutoPilot now saves a new blob containing the target OS' friendly name +- XML conversion tool can now be used with arguments +- Fixed an issue where the new AP download flow would crash with a newer target OS +- Fixed GPU listing for macOS Sonoma in the GPU checker +- More consistent help and escape menu flow keybinding +- Improved menu handling, including extreme value bounceback +- Backup of OVMF vars file is now performed during AutoPilot flow +- Resetting vNVRAM will now use local OVMF backup, to preserve user resolution settings +- Detected boot script main menu entries now use the OS release (friendly) name +- Main script is now subject to an OS platform compatibility check +- Main script arguments have been updated +- *snort* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-6.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-6.md new file mode 100644 index 0000000..6828dc8 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-6.md @@ -0,0 +1,28 @@ +--- +title: v0.9.6 +parent: Changelogs + +--- + +## v0.9.6 + +### Minor update • 17/08/2023 + +This update includes the following features / fixes / changes: + +- AutoPilot target OS stage made easier to select macOS version +- macOS Ventura support has been partially fixed; change CPU model from `Penryn` to `Skylake-Client` +- Fixed some USB XHCI issues +- Fixed an issue with OVMF files when using VFIO-PCI passthrough assistant +- Fixed restoration tools from using wrong blobs folder +- Various VFIO-PCI passthrough patches +- Minor AutoPilot UI improvements +- Small repo updater tool patch +- Config files now use sudo flagging when adding VFIO-PCI arguments +- Main menu now intelligently runs scripts as sudo if they have VFIO-PCI arguments +- *happy dying sounds* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-7.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-7.md new file mode 100644 index 0000000..6984f73 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-7.md @@ -0,0 +1,23 @@ +--- +title: v0.9.7 +parent: Changelogs + +--- + +## v0.9.7 + +### Minor update • 30/08/2023 + +This update includes the following features / fixes / changes: + +- Logfile support in AutoPilot; support will be added to other scripts in future updates +- AutoPilot now uses macOS byte sizes when creating HDD image files (1024 -> 1000) +- XML Conversion Tool can now use alternate AP reader; supporting config restructures and older AP boot scripts +- More documentation +- Made top of README a bit nicer +- *crunchy spine sounds* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/changelogs/v0-9-8.md b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-8.md new file mode 100644 index 0000000..4ea3a16 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/changelogs/v0-9-8.md @@ -0,0 +1,22 @@ +--- +title: v0.9.8 +parent: Changelogs + +--- + +## v0.9.8 + +### Minor update • 12/09/2023 + +This update includes the following features / fixes / changes: + +- Major branding additions +- Discord rich presence support +- The baseConfig has been updated to support toggling of Discord RPC +- New ULTMOS verbose boot options in new config setups +- *I can drive now, how dangerous is that?!* + +To see individual code changes, visit the project's commits page at + +> [!NOTE] +> Remember, commits by Coopydood will always be signed as **4CD28348A3DD016F** or GitHub's public key. \ No newline at end of file diff --git a/docs/dimensional-debris/src/content/docs/guides/example.md b/docs/dimensional-debris/src/content/docs/guides/example.md new file mode 100644 index 0000000..ebd0f3b --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/guides/example.md @@ -0,0 +1,11 @@ +--- +title: Example Guide +description: A guide in my new Starlight docs site. +--- + +Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. +Writing a good guide requires thinking about what your users are trying to do. + +## Further reading + +- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/docs/dimensional-debris/src/content/docs/index.mdx b/docs/dimensional-debris/src/content/docs/index.mdx new file mode 100644 index 0000000..664b681 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/index.mdx @@ -0,0 +1,36 @@ +--- +title: Welcome to Starlight +description: Get started building your docs site with Starlight. +template: splash +hero: + tagline: Congrats on setting up a new Starlight project! + image: + file: ../../assets/houston.webp + actions: + - text: Example Guide + link: /guides/example/ + icon: right-arrow + - text: Read the Starlight docs + link: https://starlight.astro.build + icon: external + variant: minimal +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +## Next steps + + + + Edit `src/content/docs/index.mdx` to see this page change. + + + Add Markdown or MDX files to `src/content/docs` to create new pages. + + + Edit your `sidebar` and other config in `astro.config.mjs`. + + + Learn more in [the Starlight Docs](https://starlight.astro.build/). + + diff --git a/docs/dimensional-debris/src/content/docs/reference/example.md b/docs/dimensional-debris/src/content/docs/reference/example.md new file mode 100644 index 0000000..0224f09 --- /dev/null +++ b/docs/dimensional-debris/src/content/docs/reference/example.md @@ -0,0 +1,11 @@ +--- +title: Example Reference +description: A reference page in my new Starlight docs site. +--- + +Reference pages are ideal for outlining how things work in terse and clear terms. +Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. + +## Further reading + +- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/docs/dimensional-debris/src/env.d.ts b/docs/dimensional-debris/src/env.d.ts new file mode 100644 index 0000000..acef35f --- /dev/null +++ b/docs/dimensional-debris/src/env.d.ts @@ -0,0 +1,2 @@ +/// +/// diff --git a/docs/dimensional-debris/src/styles/custom.css b/docs/dimensional-debris/src/styles/custom.css new file mode 100644 index 0000000..e69de29 diff --git a/docs/dimensional-debris/tsconfig.json b/docs/dimensional-debris/tsconfig.json new file mode 100644 index 0000000..bcbf8b5 --- /dev/null +++ b/docs/dimensional-debris/tsconfig.json @@ -0,0 +1,3 @@ +{ + "extends": "astro/tsconfigs/strict" +}