From 8edc0fc38ff974b86539b21b17877367847837bd Mon Sep 17 00:00:00 2001 From: rxhfcy <42669366+rxhfcy@users.noreply.github.com> Date: Mon, 8 Apr 2024 18:14:07 +0300 Subject: [PATCH] README.md: simplify and polish --- README.md | 107 +++++++++++++++++++++--------------------------------- 1 file changed, 42 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 6619ad9..0b59e0d 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ Main menu screenshot
-Select which OS you want to use next on your Apple silicon Mac. +*An alternative to the built-in Apple Silicon boot picker.* + +**Asahi Restart Helper (macOS version)** is a macOS menu bar app that +makes it easy to select which OS you want to use next. +The default Startup Disk will remain unchanged unless you explicitly choose to change it. -**Asahi Restart Helper (macOS version)** adds a macOS menu bar icon that makes it easy to restart -using whichever OS you wish. The default doesn't matter and will **not** be changed (unless you explicitly choose to). - **"Restart in Linux..."**: Restart and load **Linux** this time, even if macOS is the default - **"Restart in macOS..."**: Or restart *back into macOS*, even if Linux is the default - **Alternatively**, the app can also be used to change the default Startup Disk
@@ -25,89 +27,64 @@ using whichever OS you wish. The default doesn't matter and will **not** be chan --- Restart dialog screenshot
-2\. Click "Restart now!" in the confirmation dialog. - - -The system will now restart without asking any further questions (if the correct permissions are set). - -The default Startup Disk will **NOT** be changed. +2\. Click "Restart now!" in the confirmation dialog. The system will then restart. --- Change default startup disk dialog
-The app also allows changing the default Startup Disk directly from the menu
-(included for parity with the Linux version) - -Using the app to restart does not require changing the default. +**Alternatively**, you can use the app to change the default Startup Disk.
+(This is optional and **not required** to use the app) --- ## Build the App with Xcode: -1. Clone this repository: `git clone (this URL)` or download the zip file and extract it -2. Launch Xcode, choose "Open Existing Project..." -3. Navigate to the new folder (Xcode will automatically look for and open the `.xcodeproj` bundle) -4. You should now be able to build and test the project (please open a new issue if that was not the case!) +1. Clone this repository: `git clone https://github.com/rxhfcy/Asahi-Restart-Helper--macOS-version.git` + or download the zip file and extract it +3. Launch Xcode, choose "Open Existing Project..." +4. Navigate to the new folder (Xcode will automatically look for and open the `.xcodeproj` bundle) +5. You should now be able to build and test the project (please open a new issue if that was not the case!) ## Technical details: -This application is designed to work around the "invisibility" and slowness of the Apple silicon (ARM64) boot picker. -On traditional x86-based dual-boot systems, a boot picker will usually automatically appear on the screen on startup, -but on Apple silicon, the boot picker is only allowed to be shown -if the user physically holds down the power button for several seconds while starting up the computer. -This makes it rather inaccessible, especially for inexperienced users who aren't already familiar with this quirk. -For technical reasons, Apple's boot picker is also rather slow to load the selected OS. - -In essence, this app is a GUI to run Apple's official `bless` tool with --nextonly -(`sudo bless --mount "/Volumes/Linux Disk Name/" --setBoot --nextonly`) -to temporarily use an alternative startup disk for this restart only, and then restart. +This app is designed to address the "invisibility" and clumsiness of the Apple silicon (ARM64) boot picker. +On traditional x86-based dual-boot systems, a boot picker typically appears on the screen automatically upon startup, +but on Apple silicon, the picker will only appear if the user physically holds down the power button while booting. +This makes the boot picker rather inaccessible, particularly for new users unfamiliar with this quirk. -The default Startup Disk setting is never modified unless the user specifically chooses to do that. -Under the hood, the `alt-boot-volume` NVRAM parameter is temporarily added for the next startup only, -i.e. the `boot-volume` NVRAM parameter (the default Startup Disk setting) is not modified. +In essence, this app provides a GUI for running Apple's official `bless` command (with --nextonly), +eliminating the need to use the Apple boot picker. +Behind the scenes, `sudo bless --mount "/Volumes/Linux Disk Name/" --setBoot --nextonly` is executed +to add a temporary `alt-boot-volume` NVRAM parameter for this restart only. The default Startup Disk setting +(the `boot-volume` NVRAM parameter) remains unchanged unless the user explicitly changes it via the submenu. -Perhaps it should also be noted that the app doesn't validate whether the "Linux" disk actually is a "real" -Asahi Linux stub. It is just assumed that the "other" disk probably contains Linux. In the vast majority of cases, -this will not cause any confusion. Also, if more than one "Linux" disk is found, the menu will just list the actual -names of the "other" disks instead of displaying the normal "Restart in Linux..." item, -e.g. "Restart in macOS...", "Restart in 'Fedora Linux'..." and "Restart in 'Another Linux Distribution'...". +Note: If multiple "Linux" disk are detected, the menu will display the name of each disk instead, +e.g. *"Restart in Fedora Linux..."* and *"Restart in Another Linux Distribution..."*. +Also, note that the app doesn't verify whether the "other" disks are indeed "Linux" disks. +It simply assumes that they are likely to be "Linux". In most cases, this should not cause confusion. -Note: macOS does not allow any app to directly use the macOS standard Restart dialog, so a custom dialog must be used. -However, the "custom" restart does seem to honor any previously selected "Reopen windows when logging back in" setting -from the aforementioned system restart dialog (?) +Note: macOS does not permit apps to directly use the standard macOS Restart dialog, so a custom dialog must be used. +However, the custom restart appears to respect any previously selected "Reopen windows when logging back in" setting +from the aforementioned system restart dialog. -## Download initial demo version: +## Download: -Download:
+Download the UI demo version here:
[Asahi Restart Helper.app.zip](https://github.com/rxhfcy/Asahi-Restart-Helper--macOS-version/raw/main/misc/Asahi%20Restart%20Helper.app.zip) - Self-signed -- UI demo only -- Doesn't actually restart yet -- Can't actually change default Startup Disk yet +- UI demo only, does not actually restart the system + +## Project goals: + +- **macOS menubar icon**: Aim to have the Asahi Linux installer automatically install this app on macOS. +- **Linux System Tray icon**: Aim to have what the Asahi Linux installer installs (Fedora Asahi Remix, others) to + automatically install [the Linux version of this app](https://github.com/rxhfcy/Asahi-Restart-Helper--Linux-version) + on Linux + - Also install a GNOME extension that enables showing System Tray icons? (works on KDE Plasma) ## Requirements: -- For Apple silicon Macs only (Asahi Linux is ARM64-only) -- For macOS Ventura 13.5 or newer only (or whatever the Asahi Linux installer requires) +- Apple silicon only (Asahi Linux is ARM64-only) +- Requires macOS Ventura 13.5 or newer, as required by the Asahi Linux installer - Asahi Linux must already be installed on the computer - - Can't launch Asahi Linux installer from this app, at least for now - -## Goals: -- The actual point of this app (and the Linux version): make it easy to select which OS to use next - - instead of requiring every user to already know the holding-down-the-power-button trick - (and/or to already know how to change the default startup disk) -- Use non-technical language (give newbies a chance, experts will know how to use the app regardless of terminology) - -## Stretch goals: -- Convince the official Asahi installer to automatically install this app, i.e. add the app icon on macOS (!) -- Bonus goal: convince Asahi installer to not silently make Asahi Linux the default Startup Disk - - reason: from a new user's perspective, the installer by default completely hides all evidence of the user's - macOS installation ever having existed, unless you already happen to know the secret spell or gesture (!) - -### (Stretch goals for the Linux version) -- Convince "Linux" (currently Fedora Asahi Remix) to automatically install the Linux version of this app (add icon) - - Additional benefit: `asahi-bless` will be useful to users (required dependency) - - Also install the extension that allows showing the icon on Gnome? (KDE Plasma allows showing the icon by default) -- Bonus goal: convince the developer of `asahi-bless` (the Linux `bless` counterpart) to add more helpful - command line options, and generally make the tool easier to use # See also: [TODO.md](./Asahi%20Linux%20Helper/TODO.md)