Skip to content

Commit

Permalink
Update README and TODO (use "Option Y")
Browse files Browse the repository at this point in the history
  • Loading branch information
@rxhfcy
rxhfcy committed Apr 30, 2024
1 parent a572db6 commit e89d07f
Show file tree
Hide file tree
Showing 2 changed files with 99 additions and 108 deletions.
62 changes: 27 additions & 35 deletions Asahi Restart Helper/TODO.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,15 @@

- [ ] (todo: add link to Linux version's TODO list)
- [ ] (todo: sync macOS and Linux TODO list)
- [ ] (todo: update this TODO list to match reality)

# (NOTE: if you tweak something, please keep macOS/Linux TODOs synced!)

- [ ] 2: Make popover close/hide after user clicks "Restart..." and modal password dialog appears
- slow UI animation forbids closing the popover, but works without animations?
- [ ] 1: Code signing / workaround
- find someone willing to sign the app and probably keep signing it for years...
- or at least find some other tolerable way to not make users jump through silly Apple hoops after installation

- [ ] 2: UI note: "You should also install the corresponding Linux version of this app to easily switch back to macOS"?

- [ ] 1: Does the disk name need to be shown in the Restart confirmation popover or not?
- leaning on probably implementing this just to always be super predictable and clear
Expand Down Expand Up @@ -120,10 +124,10 @@
- Suggests that the application assists users in the boot process
- Asahi Restart Icon
- Too clumsy? Very literal and descriptive, the app does add an (Asahi) icon for restarting
- Asahi Startup Disk Icon ("Restart in macOS" / "Restart in Linux")
- Even clumsier? Even more literal and descriptive, the app is an icon to change the 'Startup Disk'
- Asahi Restart Helper Menu
- This is getting ridiculous, almost certainly too long
- Asahi Restart Helper Menu Icon
- You must be joking
- Probably too long and clumsy
- Asahi Restart
- Very short, still at least somewhat communicates the application's main function (restarting)
- Asahi OS Switcher
Expand All @@ -144,25 +148,17 @@
- Extremely literal, i.e. spell out the reason the app exists in the first place

- [ ] 1: App icon OK?
- ask for permission
- provide all sizes?
- ask for permission and use the Asahi icon?
- ...or use the Tux Linux icon instead? Or something else?
- provide all sizes (why)?

- [ ] 1: Menubar icon OK?
- ask for permission
- use a "proper" (template?) icon instead that supports macOS dark/light theme?

- [ ] 2: GitHub blurb ok?
- Compare with Linux version
- "Asahi Restart Helper: macOS menubar app to easily Restart in Linux (btw add other Asahi Linux tools later?)"
- "Asahi Restart Helper: Restart to Asahi Linux this time only (macOS menubar app)"
- "Asahi Restart Helper makes it easy to choose which OS / disk will be used to restart
(it can also change the default Startup Disk setting)"
- Asahi Restart Helper (macOS version) is a macOS toolbar app that:
- makes it easy to restart in Asahi Linux from macOS
- for parity with Linux version of the app, offers an option to select default Startup Disk from within the app
- maybe later: updates m1n1 (by launching the Asahi installer via a special command line argument?)
- maybe later: add other Asahi installer related tasks (launch Asahi installer, etc?)
- obviously will have to ask for permission before using the Asahi name but that won't be relevant for a while
- ask for permission and use the Asahi icon?
- ...or use the Tux Linux icon instead? Or something else?
- use a "proper" (boring one color template?) icon instead that supports macOS dark/light theme (why)?

- [ ] 2: GitHub blurb and README ok?
- Sync with Linux version

- [ ] 3: Scope creep? What should the project (not) do?
- Could the name be "Asahi Linux Helper" instead? Does the Asahi project want a more general "helper"?
Expand All @@ -171,8 +167,8 @@
- potential future "helper" functionality: run Asahi installer
- potential future "helper" functionality (stretch goal): uninstall Asahi Linux

- [ ] 2: CLI installer: external apps (e.g. Asahi installer) to silently sudo install the app in an already useful state
- require sudo
- [ ] 2: CLI installer: allow external apps (e.g. Asahi installer) to silently sudo install the app in a useful state
- requiring sudo mandatory?
- make app show icon (add to macOS Login Items) --add-to-login-items or something?
- make app not ask password (install privileged helper app) --install-privileged-helper-app or something?
- make app not ask questions (permission prompt can't be avoided, right?)
Expand All @@ -182,15 +178,15 @@
- installing helper tool? (yes/no)

- [ ] 2: Handle user having manually disabled macOS permission from System Settings (after having allowed it before)
- probably needs another pref for "User has given system permission"
- probably needs another hidden pref for "User has given system permission"
- to test, always perform dummy action that requires same permissions (after pressing "Restart", before sudo bless)
- if the dummy action failed (detect error code or variable), explain and offer link to correct place in
System Settings (check if different in macOS 13/14/newer?)

- [ ] 3: Handle not having any other viable disks ("Linux")
- [ ] 3: Handle not having any other viable disks (no "Linux" to restart in)
- why would anyone run the app with just the one OS?
- explain that no other disk were detected
- offer to run Asahi Linux installer?
- offer to run Asahi Linux installer or at least a link to asahilinux.org?

- [ ] 3: Consider showing a user-friendly error if using Intel
- reason: if release version is (accidentally?) built Universal, it will not show an error by default
Expand All @@ -206,7 +202,7 @@

- [ ] 3: Handle other errors (what? where?)

- [ ] 3: Uninstaller (don't leave privileged helper app and other cruft behind)?
- [ ] 3: Uninstaller (don't leave the privileged helper app and other cruft behind)?
- remove privileged helper app
- remove from Login Items
- clear all prefs
Expand All @@ -218,18 +214,13 @@
- suggestions for wording/spelling (titles, tooltips)?

- [ ] 3: Write documentation
- proper README.md
- is anything else necessary?
- is the README enough or is something else needed?

- [ ] 3: Write tests
- Unit tests
- might need to sometimes use weird custom mock tests because the app writes to NVRAM, GitHub won't test that
- might need to sometimes use weird custom mock tests because the app writes to NVRAM (GitHub won't test that)
- UI tests

- [ ] 1: Code signing
- find someone willing to sign the code and ready to keep signing it for years...
- or at least find some other tolerable way to not make users jump through hoops after installation

----------------------------------------

## 4: WON'T HAVE (not worth it / out of scope / feature creep, revisit this list periodically):
Expand Down Expand Up @@ -370,3 +361,4 @@
- [x] Placeholder testing support (dummy Unit Tests and UI Tests, currently only test if the app builds and launches)
- [x] 2: Confirmed that the app wouldn't even work on Intel (sudo bless --nextonly gives an error)
- [x] 1: Mock UI for changing default Startup Disk (submenu)
- [x] 2: Make popover close/hide after user clicks "Restart..."
145 changes: 72 additions & 73 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,93 +1,96 @@
```diff
- FIXME: We're considering 4 UI options
- and can't decide which one is best.
- NOTE:
- Once we've decided on the best compromise for
```
[(the Linux version UI)](https://github.com/rxhfcy/Asahi-Restart-Helper--Linux-version)
```diff
- AND if "Option Y" (this version) is not chosen,
- the macOS version will be updated to match the UI of the Linux version.
```

**Option A (THIS README)**: Boot menu.
This option lets users select from all disks and restart **WITHOUT CHANGING** the default 'Startup Disk'.
However, it does provide a submenu for changing the default 'Startup Disk'.

This is currently the only version implemented on macOS.
Once we've decided on the best compromise for
[the Linux version](https://github.com/rxhfcy/Asahi-Restart-Helper--Linux-version) (**Option Y**? **Option A**?),
the macOS version will be updated to match the UI of the Linux version.

---

# Asahi Linux Helper<br>(macOS version)
# Asahi Startup Disk Icon<br>("Restart in Linux")

<img src="./misc/Menu_Screenshot.png" width="25%" alt="Main menu screenshot"><br>

***A faster alternative to the "hidden" Apple silicon Boot Menu.***

**Asahi Restart Helper (macOS version)** makes it easy to
restart the computer into [Asahi Linux](https://asahilinux.org/).
**Asahi Startup Disk Icon** makes it easy to
restart your Apple silicon Mac into [Asahi Linux](https://asahilinux.org/) (from macOS).

**NOTE: You should also install the
[corresponding Linux version](https://github.com/rxhfcy/Asahi-Restart-Helper--Linux-version),<br>
[corresponding Linux version ("Restart in macOS")](https://github.com/rxhfcy/Asahi-Restart-Helper--Linux-version),<br>
to make it equally easy to return back to macOS from Linux!**

## Usage

Click the system tray icon and select the OS you want to restart into:

- **Restart in Linux**: Restart and load **Linux** this time, even if Linux is the default.
- **Restart macOS**: or Restart *back into macOS*, even if Linux is the default.
Click the app's menubar icon to access the menu:

Or use the other menu items:
- **Restart in Linux**: This sets **Linux** as the default 'Startup Disk' and restarts the computer (in Linux).<br>

- **Change default 'Startup Disk'**: Use this submenu if you want to change the default 'Startup Disk' setting.
- **Preferences**: This dialog allows you to enable showing the icon after logging in, or to set up password-free usage.
- (if multiple "Linux" disks are detected, they will be listed in the menu by their respective disk names)

Restarting never changes the default 'Startup Disk' setting.
- **Change default 'Startup Disk'**: Use this option to change the default 'Startup Disk' without restarting.
For example, switch the default back to macOS.
- **Preferences**: This allows you to set the application to always display its menubar icon after login.
You can also enable password-free usage by installing a privileged helper tool.

The 'Startup Disk' determines the operating system the computer always loads by default after shutting down,
or after restarting "normally" without using this application.

The current default is indicated in the menu with a "(current default)" label.
The 'Startup Disk' determines the operating system that your computer will load by default
after a shutdown or a "normal" restart.

## Features

- **Fast and Easy to Use**: Just click the icon and select the OS you want to use next.
- **Doesn't Force 'Startup Disk' Change**: Current default 'Startup Disk' setting will not change
unless you *choose* to change it from the submenu.
- **Same Boot Menu GUI on Both macOS and Linux**: Use the same GUI on both operating systems by
- **Fast and Easy to Use**: Just click the icon and then "Restart in Linux".
- **Changes 'Startup Disk' Setting**: Restarting in Linux changes the default 'Startup Disk' setting -> Linux,
to make shutting down and restarting "normally" always return back to the same OS.
- **Same GUI on Both macOS and Linux**: Use the same GUI on both operating systems by
also installing the corresponding
[Linux version](https://github.com/rxhfcy/Asahi-Restart-Helper--Linux-version) on Linux.
[Linux version ("Restart in macOS")](https://github.com/rxhfcy/Asahi-Restart-Helper--Linux-version) on Linux.

## Who should use it and why?
## Who should use this and why?

Beginners and expert users alike benefit from using this application.
It simplifies dual-booting Linux and macOS on Apple Silicon Macs. Apple's native boot menu is "hidden" on start-up,
hard to access, and slow to use, leaving room for improvement.
The application fills this gap by offering a more convenient "OS picker" or "boot menu".
Both beginners and expert users will hopefully find this application beneficial.
It simplifies the process of dual-booting Linux and macOS on Apple Silicon Macs.

Apple has intentionally made it difficult to use any OS other than macOS.
This project aims to mitigate the friction caused by Apple's design decisions
when using two or more operating systems on the computer.

Because Apple decided to not allow showing the boot menu on start-up,
they also had to introduce the somewhat confusingly named concept of the 'Startup Disk',
which determines the default OS that is always loaded after shutting down the computer or restarting it "normally"
using the native OS restart functionality.
This application also simplifies restarting into Linux itself,
even if macOS happens to currently be set as the 'Startup Disk'.
Apple's native boot menu is hidden on start-up, making it unnecessarily hard to access and slow to use.
This application works around the "missing" boot menu and makes switching to "the other OS"
more convenient and accessible.

## Screenshots:

<img src="./misc/Menu_Screenshot.png" width="50%" alt="Main menu screenshot"><br>

```diff
- TODO: update screenshot to
- remove the "Restart in macOS" stuff from an earlier UI iteration
```

1\. Click "Restart in Linux..." from the menu to restart in Linux next.<br>
(i.e. restart in Linux this time only without changing the default Startup Disk!)

---

<img src="./misc/Restart_Dialog_Screenshot.png" width="50%" alt="Restart dialog screenshot"><br>

```diff
- TODO: update screenshot to
- explicitly state that "name of Linux disk" will be used as the default 'Startup Disk'
```

2\. Then click "Restart now!" from the Restart dialog.
The system will restart without asking any further questions (if the correct permissions etc are set).

---

<img src="./misc/Change_Default_Screenshot.png" width="50%" alt="Change default startup disk dialog"><br>

```diff
- TODO: update submenu in screenshot to
- also show the current default Startup Disk as disabled + "(current default)"

- TODO: update screenshot to
- remove the "Restart in macOS" stuff from an earlier UI iteration
```

The app can also be used to change the default Startup Disk directly from the menu<br>

---
Expand All @@ -105,6 +108,8 @@ The app can also be used to change the default Startup Disk directly from the me

## Download initial demo version:

**TODO: update demo app UI and name**

Download:
[Asahi Linux Helper.app.zip](./misc/Asahi%20Linux%20Helper.app.zip)

Expand All @@ -115,28 +120,21 @@ Download:

## Technical overview

This application provides a GUI that replaces the "hidden" native boot menu
by running the Apple's `bless` tool with the `--nextonly` argument.
This adds a temporary NVRAM parameter (`alt-boot-volume`) for this restart only,
leaving the default 'Startup Disk' setting (the `boot-volume` NVRAM parameter) unchanged
unless the user explicitly modifies it using the submenu.

The application was designed to
not always change the default 'Startup Disk' setting when switching to the other OS,
because this can arguably prevent confusion for users who don't want to have to
always keep track of the current default setting after shutting down the computer
(i.e. to make it more predictable which OS will load after starting up the computer in that case).
It is arguably best to use whichever OS is used more frequently as the default Startup Disk,
instead of continuously changing it for little reason,
which can make the 'Startup Disk' setting itself feel almost random and useless.

When exactly two bootable disks are detected, the current disk is always displayed as "macOS" in the menu,
and the other disk is assumed to be the "Linux" disk.
If three or more disks are detected, any other disks are listed in the menu using their full disk names in this case.

Note: macOS does not permit apps to directly use the standard macOS Restart dialog, so a custom dialog must be used.
Because Apple decided to not allow showing the boot menu on start-up,
they also had to introduce the somewhat confusingly named concept of the 'Startup Disk',
which determines the default OS that is always loaded after shutting down the computer or restarting it "normally".

This application provides a GUI that makes it easy to switch to the other OS,
by running the Apple's `bless` command line tool and then restarting.
Using `bless` without `--nextonly` changes the default 'Startup Disk' setting (the `boot-volume` NVRAM parameter).

When exactly two bootable disks are detected, the "other" disk is assumed to be the "Linux" disk.
If three or more disks are detected, any "other" disks are listed in the menu using their full disk names.

NOTE: macOS does not permit apps to directly use the standard macOS Restart dialog,
so a custom restart 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 (TODO: verify).
from the aforementioned system restart dialog **(TODO: test and verify this)**.

## Requirements

Expand All @@ -154,11 +152,12 @@ This project is licensed under the [MIT License](./LICENSE).
## Project goals

The ultimate goal of this project is to have the icon installed by default (both on Linux and macOS)
automatically after the user installs Asahi Linux.
automatically when the official [Asahi Linux installer](https://asahilinux.org) is used.

- **Linux System Tray icon**: The goal is to convince Asahi Linux distributions (Fedora Asahi Remix, others?)
- **Linux System Tray icon**: The goal is to convince Fedora Asahi Remix
to automatically install the Linux version of this application (add the icon in Linux/KDE System Tray)
- Also install a GNOME extension that allows showing the System Tray icon
- "asahi-bless daemon" required first (todo (Rust))
- Bonus: also install a GNOME extension that allows showing the System Tray icon
on GNOME?
- **macOS menubar icon**: The goal is to also convince the Asahi Linux installer to automatically install
the macOS version of this application (add the icon in macOS menubar)
Expand Down

0 comments on commit e89d07f

Please sign in to comment.