From cde573a13f1fe9eb21d22ff2669717b2ceaa0ff6 Mon Sep 17 00:00:00 2001 From: Stevex <310088924+kik4311@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:17:22 +0300 Subject: [PATCH 1/2] Linux app: the four steps in GTK 4 Adds linux/, a GTK 4 window for Check this PC, Build the Mac setup, Your BIOS steps and Create the macOS stick. It runs the same engine as the Windows app; the ACPI copy and the USB write ask policykit for root. The Linux scan translates DRM connector names and leaves out ACPI paths outside _SB before the engine validates the report. The stick writer and its elevated entry point are p1401/linuxusb.py and p1401/linuxroot.py. Signed-off-by: Stevex <310088924+kik4311@users.noreply.github.com> --- DEVELOPING.md | 12 + README.md | 1 + docs/HOW-IT-WORKS.md | 3 + linux/1401 | 5 + linux/1401.desktop | 7 + linux/1401.py | 1097 ++++++++++++++++++++++++++++++++++++ linux/README.md | 98 ++++ linux/build.sh | 41 ++ p1401/linuxroot.py | 158 ++++++ p1401/linuxusb.py | 697 +++++++++++++++++++++++ p1401/report.py | 30 + p1401/scan.py | 27 +- tests/test_linux_report.py | 66 +++ tests/test_linux_root.py | 117 ++++ tests/test_linux_usb.py | 289 ++++++++++ 15 files changed, 2644 insertions(+), 4 deletions(-) create mode 100755 linux/1401 create mode 100644 linux/1401.desktop create mode 100644 linux/1401.py create mode 100644 linux/README.md create mode 100755 linux/build.sh create mode 100644 p1401/linuxroot.py create mode 100644 p1401/linuxusb.py create mode 100644 tests/test_linux_report.py create mode 100644 tests/test_linux_root.py create mode 100644 tests/test_linux_usb.py diff --git a/DEVELOPING.md b/DEVELOPING.md index 1f7b46ff..b4478360 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -19,6 +19,7 @@ This is the guide for working on 1401's source. To report a bug, see `CONTRIBUTI |---|---|---|---| | Engine (scan, build, BIOS guide, stick writer) | `p1401/` | any OS for the tests; Windows in the app | Python 3.12 or newer | | Windows app (the window) | `windows/App/` | Windows | .NET SDK 8.0.425 (`global.json` pins it), Visual Studio C++ tools for `native/` | +| Linux app (the same four steps) | `linux/` | Linux | Python 3.12 or newer, GTK 4, PyGObject, polkit | | Mac app (after the install) | `mac/` | macOS 15 or newer | Xcode (Swift 6.3 and 6.4 both build it) | | UEFI loader (experimental, unused by the app) | `loader/` | QEMU | Rust | | Upstream engines (pinned copies) | `upstream/` | | do not edit; `PINNED.json` names the commits | @@ -31,6 +32,8 @@ Most work is in the engine, and the engine's tests need no special hardware. `nullmoth.py` (Build the Mac setup and its rules), `guide.py` (Your BIOS steps), `usbwriter.py` (Create the macOS stick), `report.py` (Send logs). `community_gpu.py` lists other people's GPU drivers and when to mention them. - `windows/App/`: the C# window. It runs each engine step as `python -u -m ` and shows its output. +- `linux/`: the GTK 4 window, its launcher, and `linuxusb.py`'s Linux entry point in `p1401/`. It runs the same engine + modules as the C# window; root steps go through `pkexec`. - `mac/`: the Mac app that finishes the setup after macOS is installed. `mac/build.sh` builds it and runs its own tests. - `tests/`: unit tests (`test_*.py`), the hardware corpus (`tests/corpus/`), and the corpus runner (`run_corpus.py`). - `tools/`: release, packaging and corpus tools. @@ -81,6 +84,15 @@ dotnet build windows/App/App.csproj --configuration Release --output build `.github/workflows/windows-candidate.yml` is the full packaging run, step by step. +**Linux app:** + +```bash +bash linux/build.sh /tmp/1401-linux +``` + +It runs the Linux writer tests and a window self-test, then stages a folder that runs with `./1401`. The packages it +needs and the places it keeps scans and logs are in `linux/README.md`. + **Mac app:** ```bash diff --git a/README.md b/README.md index 70f3f6c4..34b25157 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ Install macOS on the PC you already own: the reverse of Boot Camp. 1401 runs on an OpenCore setup for it and writes a macOS install stick. It is free and open source. - Download: [releases page](https://github.com/nullmoth/1401/releases) (`1401-Windows-.zip`) +- Linux: [build and run it from source](linux/README.md); the window does the same four steps - Changes: [CHANGELOG.md](CHANGELOG.md) - Problems: [troubleshooting](docs/TROUBLESHOOTING.md) - How it works: [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md) diff --git a/docs/HOW-IT-WORKS.md b/docs/HOW-IT-WORKS.md index e8c78b4e..d57efe67 100644 --- a/docs/HOW-IT-WORKS.md +++ b/docs/HOW-IT-WORKS.md @@ -3,6 +3,9 @@ 1401 is a Windows app that turns a USB stick into a macOS installer built for one specific PC. This page follows the four steps of the app through the code. +The source tree also has a Linux window (`linux/README.md`) that runs the same engine steps; the paths below describe +the Windows release, which is what most people use. + > 1401 is new and may not work on every PC. If it does not work on yours, set up OpenCore by hand with the > [OpenCore Install Guide](https://dortania.github.io/OpenCore-Install-Guide/). The NVIDIA driver and its Mac app work > on any OpenCore setup. diff --git a/linux/1401 b/linux/1401 new file mode 100755 index 00000000..e1e2edbc --- /dev/null +++ b/linux/1401 @@ -0,0 +1,5 @@ +#!/bin/sh +# Starts 1401 from this checkout. The engine and the window need the repository around them, so this stays in linux/. +set -eu +here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +exec python3 -u "$here/1401.py" "$@" diff --git a/linux/1401.desktop b/linux/1401.desktop new file mode 100644 index 00000000..d766ed71 --- /dev/null +++ b/linux/1401.desktop @@ -0,0 +1,7 @@ +[Desktop Entry] +Type=Application +Name=1401 +Comment=Build a macOS installer for this PC +Exec=@EXEC@ +Terminal=false +Categories=System; diff --git a/linux/1401.py b/linux/1401.py new file mode 100644 index 00000000..23b9478e --- /dev/null +++ b/linux/1401.py @@ -0,0 +1,1097 @@ +#!/usr/bin/env python3 +"""1401 for Linux: check this PC, build the OpenCore setup, show the BIOS steps, and write the macOS stick. + +GTK 4 and PyGObject. The window only collects choices and runs the same engine commands the Windows app runs; every +step that needs root (ACPI tables, the USB erase) goes through policykit. +""" +import json +import os +import re +import shlex +import shutil +import subprocess +import sys +import threading +import uuid + +import gi + +gi.require_version("Gtk", "4.0") +from gi.repository import Gio, GLib, Gtk # noqa: E402 + +HERE = os.path.dirname(os.path.abspath(__file__)) +REPO = os.path.dirname(HERE) +sys.path.insert(0, REPO) + +from p1401 import linuxusb # noqa: E402 + +APP_NAME = "1401" +STEPS = ["Introduction", "Check this PC", "Build the Mac setup", "Your BIOS steps", "Create the macOS stick", "Done"] +OS_CHOICES = [("macOS 15 Sequoia", "24", False), ("macOS 26 Tahoe", "25", False), + ("macOS 14 Sonoma (experimental)", "23", True), ("macOS 13 Ventura (experimental)", "22", True), + ("macOS 12 Monterey (experimental)", "21", True), ("macOS 11 Big Sur (experimental)", "20", True), + ("macOS 10.15 Catalina (experimental)", "19", True), ("macOS 10.14 Mojave (experimental)", "18", True), + ("macOS 10.13 High Sierra (experimental)", "17", True), ("macOS 10.12 Sierra (experimental)", "16", True)] +MACOS_NAMES = {"25": "Tahoe", "24": "Sequoia", "23": "Sonoma", "22": "Ventura", "21": "Monterey", "20": "Big Sur", + "19": "Catalina", "18": "Mojave", "17": "High Sierra", "16": "Sierra", "15": "El Capitan"} +OPEN_CORE_GUIDE = "https://dortania.github.io/OpenCore-Install-Guide/" +MAX_LOG_LINES = 5000 +# The engine records the ACPI disassembler's printout as a notice when it moves on to its next question. The log keeps +# it for support; the result summary skips it, because it is thousands of characters about duplicate names in the +# firmware tables and reads like a failure even when the build passed. +_ACPI_DUMP = re.compile(r"^(?:ACPI(?::| Error:)|Firmware Error|Pass \d parse|Parsing |Disassembly |ASL Output:|" + r"File appears to be binary|Input file )", re.M) + + +def state_dir(): + base = os.environ.get("XDG_STATE_HOME") or os.path.join(os.path.expanduser("~"), ".local", "state") + return os.path.join(base, "nullmoth", "1401") + + +def data_dir(): + base = os.environ.get("XDG_DATA_HOME") or os.path.join(os.path.expanduser("~"), ".local", "share") + return os.path.join(base, "nullmoth", "1401") + + +def interpreter(): + return [sys.executable, "-E", "-s", "-u"] + + +def quoted(command): + return " ".join(shlex.quote(part) for part in command) + + +class Window(Gtk.ApplicationWindow): + def __init__(self, app): + super().__init__(application=app, title=APP_NAME) + self.set_default_size(1040, 760) + self.set_size_request(860, 620) + self.work = state_dir() + os.makedirs(self.work, exist_ok=True) + self.log_path = os.path.join(self.work, "1401.log") + self._rotate_log() + self.log_file = open(self.log_path, "a", encoding="utf-8", buffering=1) + self.busy = False + self.page = 0 + self.scanned = False + self.built = False + self.written = False + self.scan_id = None + self.scan_dir = None + self.efi_dir = os.path.join(self.work, "efi") + self.guide_file = None + self.macos_full = "" + self.darwin = "24" + self.summary = "" + self.usb_disks = [] + self.full_pkg = None + self.recovery_dir = os.path.join(data_dir(), "Recovery") + self.last_lines = [] + self._pulse_id = None + self._have_progress = False + self._log_lines = 0 + self.busy_controls = [] + + self.header = Gtk.HeaderBar() + self.header.set_title_widget(Gtk.Label(label=APP_NAME)) + self.set_titlebar(self.header) + + root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) + self.set_child(root) + main = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=0) + main.set_vexpand(True) + root.append(main) + + sidebar = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=2) + sidebar.set_size_request(228, -1) + sidebar.set_margin_top(18) + sidebar.set_margin_bottom(18) + sidebar.set_margin_start(12) + sidebar.set_margin_end(12) + main.append(sidebar) + self.side_labels = [] + for index, step in enumerate(STEPS): + label = Gtk.Label(label=f"{index + 1}. {step}", xalign=0) + label.set_margin_top(6) + label.set_margin_bottom(6) + label.set_margin_start(8) + label.set_margin_end(8) + sidebar.append(label) + self.side_labels.append(label) + sidebar.append(Gtk.Separator(orientation=Gtk.Orientation.HORIZONTAL)) + self.side_note = Gtk.Label(label="Nothing on this PC is uploaded. Logs stay in " + self.work, xalign=0) + self.side_note.set_wrap(True) + self.side_note.add_css_class("dim-label") + self.side_note.set_margin_top(12) + sidebar.append(self.side_note) + + main.append(Gtk.Separator(orientation=Gtk.Orientation.VERTICAL)) + + right = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=10) + right.set_hexpand(True) + right.set_margin_top(18) + right.set_margin_bottom(12) + right.set_margin_start(20) + right.set_margin_end(20) + main.append(right) + + self.title = Gtk.Label(xalign=0) + self.title.add_css_class("title-1") + right.append(self.title) + self.note = Gtk.Label(xalign=0) + self.note.set_wrap(True) + right.append(self.note) + + self.stack = Gtk.Stack() + self.stack.set_vexpand(True) + self.stack.set_vhomogeneous(False) + self.stack.set_transition_type(Gtk.StackTransitionType.CROSSFADE) + # A page can be taller than the window (the build result, a small screen). Scroll the page, not the whole + # window: the Back/Continue buttons below the stack have to stay reachable. + page_scroller = Gtk.ScrolledWindow() + page_scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC) + page_scroller.set_vexpand(True) + page_scroller.set_child(self.stack) + right.append(page_scroller) + self.pages = [self._page_intro(), self._page_check(), self._page_build(), self._page_bios(), + self._page_write(), self._page_done()] + for index, page in enumerate(self.pages): + self.stack.add_named(page, f"page{index}") + + self.progress = Gtk.ProgressBar() + self.progress.set_show_text(True) + self.progress.set_text("") + self.progress.set_visible(False) + right.append(self.progress) + + self.log_view = Gtk.TextView() + self.log_view.set_editable(False) + self.log_view.set_cursor_visible(False) + self.log_view.set_monospace(True) + self.log_view.set_wrap_mode(Gtk.WrapMode.WORD_CHAR) + scroller = Gtk.ScrolledWindow() + scroller.set_policy(Gtk.PolicyType.AUTOMATIC, Gtk.PolicyType.AUTOMATIC) + scroller.set_child(self.log_view) + scroller.set_size_request(-1, 180) + self.log_scroller = scroller + right.append(scroller) + + footer = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) + footer.set_margin_top(4) + self.back = Gtk.Button(label="Back") + self.back.connect("clicked", lambda _b: self.go(self.page - 1)) + footer.append(self.back) + spacer = Gtk.Box() + spacer.set_hexpand(True) + footer.append(spacer) + self.next = Gtk.Button() + self.next.add_css_class("suggested-action") + self.next.connect("clicked", lambda _b: self.on_next()) + footer.append(self.next) + right.append(footer) + + self.busy_controls = [self.back, self.next, self.check_again, self.stick_refresh, self.open_guide] + self.connect("close-request", self._on_close) + self.go(0) + self.fill_sticks() + self._resume_session() + GLib.idle_add(self._check_engine) + + def _rotate_log(self): + try: + if os.path.getsize(self.log_path) > 4 * 1024 * 1024: + os.replace(self.log_path, self.log_path + ".old") + except OSError: + pass + + def _session_file(self): + return os.path.join(self.work, "1401-session.json") + + def _save_session(self): + """Keep the last scan and build across a restart; the USB write itself is never resumed.""" + if not self.scan_id or not self.scan_dir: + return + state = {"scan_id": self.scan_id, "built": self.built, "macos_version": self.macos_full, + "darwin": self.darwin, "summary": self.summary, + "guide": os.path.basename(self.guide_file) if self.guide_file else "", + "experimental": self.experimental.get_active(), "persistent": self.persistent.get_active(), + "external": self.external.get_active(), "new_identity": self.new_identity.get_active()} + try: + with open(self._session_file() + ".tmp", "w", encoding="utf-8") as fh: + json.dump(state, fh) + os.replace(self._session_file() + ".tmp", self._session_file()) + except OSError: + pass # losing the resume point is not worth stopping a finished build for + + def _resume_session(self): + """Start from the last finished scan, and from its build when the EFI and session agree.""" + try: + with open(self._session_file(), encoding="utf-8") as fh: + state = json.load(fh) + except (OSError, ValueError): + return + if not isinstance(state, dict): + return + scan_id = state.get("scan_id") + if not isinstance(scan_id, str) or not re.fullmatch(r"[0-9a-f]{32}", scan_id): + return + scan_dir = os.path.join(self.work, "scan-" + scan_id) + if not (os.path.isfile(os.path.join(scan_dir, "Report.json")) and + os.path.isdir(os.path.join(scan_dir, "ACPI"))): + return + self.scan_id, self.scan_dir, self.scanned = scan_id, scan_dir, True + self.load_facts() + self.check_note.set_text("This PC was checked. Continue to build the startup files.") + self.go(1) + darwin = str(state.get("darwin") or "") + index = next((i for i, (_, value, _) in enumerate(OS_CHOICES) if value == darwin), None) + if index is not None: + self.os_pick.set_selected(index) + self.darwin = darwin + for key, button in (("experimental", self.experimental), ("persistent", self.persistent), + ("external", self.external), ("new_identity", self.new_identity)): + button.set_active(bool(state.get(key))) + if not state.get("built") or not os.path.isfile(os.path.join(self.work, "efi", "EFI", "OC", "config.plist")): + return + self.macos_full = str(state.get("macos_version") or "") + self.summary = str(state.get("summary") or "") + self.built = True + self.build_summary.set_text(self.summary) + guide = os.path.join(self.work, os.path.basename(str(state.get("guide") or ""))) + if state.get("guide") and os.path.isfile(guide): + self.guide_file = guide + self.guide_label.set_text(guide) + self.go(2) + if not self.guide_file: + self._make_guide() + + # --- pages -------------------------------------------------------------------------------------------------- + + def _page_intro(self): + box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) + text = Gtk.Label(xalign=0) + text.set_wrap(True) + text.set_text("1401 turns a USB stick into a macOS installer built for this PC, the way Boot Camp put " + "Windows on a Mac.\n\nIt checks this PC, builds the startup files macOS needs for the exact " + "hardware, shows the BIOS settings this board needs, and writes the install stick. Windows on " + "this PC is not touched.\n\nYou need an internet connection and a USB stick of 4 GB or more " + "that can be erased.") + box.append(text) + caution = Gtk.Label(xalign=0) + caution.set_wrap(True) + caution.add_css_class("dim-label") + caution.set_text("1401 is new and may not work on every PC. If it does not work on yours, set up OpenCore " + "by hand with the guide below; the NullMoth app works on any OpenCore setup.") + box.append(caution) + link = Gtk.LinkButton(uri=OPEN_CORE_GUIDE, label="OpenCore Install Guide") + box.append(link) + return box + + def _page_check(self): + box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) + self.facts = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=6) + box.append(self.facts) + self.check_note = Gtk.Label(xalign=0) + self.check_note.set_wrap(True) + self.check_note.add_css_class("dim-label") + self.check_note.set_text("The check reads the processor, board, graphics, network and storage, then copies " + "this PC's ACPI tables. It takes about a minute. Linux will ask for your password " + "once so the tables can be read.") + box.append(self.check_note) + self.check_again = Gtk.Button(label="Check this PC again") + self.check_again.set_halign(Gtk.Align.START) + self.check_again.connect("clicked", lambda _b: self.start_scan(force=True)) + box.append(self.check_again) + return box + + def _page_build(self): + box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) + row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=10) + row.append(Gtk.Label(label="macOS version")) + self.os_pick = Gtk.DropDown.new_from_strings([name for name, _, _ in OS_CHOICES]) + self.os_pick.set_selected(0) + self.os_pick.connect("notify::selected", lambda *_a: self._build_options_changed()) + row.append(self.os_pick) + box.append(row) + self.experimental = Gtk.CheckButton(label="Include experimental community drivers (off unless you need them)") + self.experimental.connect("toggled", lambda *_a: self._build_options_changed()) + box.append(self.experimental) + self.persistent = Gtk.CheckButton(label="Persistent NVRAM on AMD (for iMessage and the startup disk)") + self.persistent.connect("toggled", lambda *_a: self._build_options_changed()) + box.append(self.persistent) + self.external = Gtk.CheckButton(label="Install macOS on a drive macOS can see when the internal drives are hidden") + self.external.connect("toggled", lambda *_a: self._build_options_changed()) + box.append(self.external) + self.new_identity = Gtk.CheckButton(label="Use a new serial number instead of the previous build's") + self.new_identity.connect("toggled", lambda *_a: self._build_options_changed()) + box.append(self.new_identity) + self.build_summary = Gtk.Label(xalign=0) + self.build_summary.set_wrap(True) + self.build_summary.set_selectable(True) + box.append(self.build_summary) + self.build_note = Gtk.Label(xalign=0) + self.build_note.set_wrap(True) + self.build_note.add_css_class("dim-label") + self.build_note.set_text("1401 downloads OpenCore and the drivers, builds the startup files for the chosen " + "macOS, and checks them with OpenCore's own validator.") + box.append(self.build_note) + return box + + def _page_bios(self): + box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) + text = Gtk.Label(xalign=0) + text.set_wrap(True) + text.set_text("The BIOS steps follow this scan and the startup files just built. Check the menu names in " + "your board manual, and take a photo of the settings you change before restarting.") + box.append(text) + self.open_guide = Gtk.Button(label="Open the BIOS steps") + self.open_guide.set_halign(Gtk.Align.START) + self.open_guide.connect("clicked", lambda _b: self.show_guide()) + box.append(self.open_guide) + self.guide_label = Gtk.Label(xalign=0, label="The steps appear here after a build.") + self.guide_label.set_wrap(True) + self.guide_label.set_selectable(True) + self.guide_label.add_css_class("dim-label") + box.append(self.guide_label) + link = Gtk.LinkButton(uri=OPEN_CORE_GUIDE, label="OpenCore Install Guide, for reference") + box.append(link) + return box + + def _page_write(self): + box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) + warning = Gtk.Label(xalign=0) + warning.set_wrap(True) + warning.add_css_class("warning") + warning.set_text("Everything on the chosen stick is erased. Pick the stick carefully.") + box.append(warning) + row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=10) + row.append(Gtk.Label(label="USB stick")) + self.stick_drop = Gtk.DropDown.new_from_strings(["No USB stick found"]) + self.stick_drop.set_hexpand(True) + self.stick_drop.connect("notify::selected", lambda *_a: self._stick_changed()) + row.append(self.stick_drop) + self.stick_refresh = Gtk.Button(label="Refresh") + self.stick_refresh.connect("clicked", lambda _b: self.fill_sticks()) + row.append(self.stick_refresh) + box.append(row) + self.stick_info = Gtk.Label(xalign=0) + self.stick_info.set_wrap(True) + self.stick_info.add_css_class("dim-label") + box.append(self.stick_info) + self.full_installer = Gtk.CheckButton( + label="Put Apple's full macOS installer on the stick too (32 GB or more, second exFAT partition)") + self.full_installer.connect("toggled", lambda *_a: self._stick_changed()) + box.append(self.full_installer) + recovery_row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=10) + self.recovery_button = Gtk.Button(label="Use a recovery image I already have...") + self.recovery_button.connect("clicked", lambda _b: self.pick_recovery()) + recovery_row.append(self.recovery_button) + self.recovery_label = Gtk.Label(xalign=0) + self.recovery_label.set_hexpand(True) + self.recovery_label.set_wrap(True) + self.recovery_label.add_css_class("dim-label") + self.recovery_label.set_text("Apple's recovery image is downloaded after the stick is erased.") + recovery_row.append(self.recovery_label) + box.append(recovery_row) + self.write_note = Gtk.Label(xalign=0) + self.write_note.set_wrap(True) + self.write_note.add_css_class("dim-label") + self.write_note.set_text("1401 downloads macOS from Apple onto the stick, adds the startup files, and " + "reads them back. A 16 GB stick is enough for the online installer.") + box.append(self.write_note) + return box + + def _page_done(self): + box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) + text = Gtk.Label(xalign=0) + text.set_wrap(True) + text.set_text("The macOS stick is ready.\n\n" + "1. Restart and open the board's boot menu (the key is in the BIOS steps), then choose the " + "stick.\n" + "2. In the 1401 boot menu choose \"Install macOS\" and follow Apple's installer. The screen can " + "stay still for up to two minutes while macOS is read from the stick: do not restart.\n" + "3. When macOS is running, open the NullMoth folder on the stick to finish the NVIDIA driver, " + "if this PC needed it.") + box.append(text) + return box + + # --- state -------------------------------------------------------------------------------------------------- + + def go(self, page): + if self.busy or page < 0 or page >= len(STEPS): + return + self.page = page + self.stack.set_visible_child_name(f"page{page}") + self.title.set_text(STEPS[page]) + for index, label in enumerate(self.side_labels): + label.remove_css_class("heading") + label.remove_css_class("dim-label") + if index == page: + label.add_css_class("heading") + elif index > page: + label.add_css_class("dim-label") + self.back.set_sensitive(0 < page < len(STEPS) - 1) + text = "Continue" + if page == 0: + text = "Get started" + elif page == 1 and not self.scanned: + text = "Check this PC" + elif page == 2 and not self.built: + text = "Build" + elif page == 4 and not self.written: + text = "Erase and create" + elif page == 5: + text = "Close" + self.next.set_label(text) + self._set_note(page) + self.log_scroller.set_visible(page in (1, 2, 4)) + self.progress.set_visible(self.busy and page in (1, 2, 4)) + if page == 4: + self.fill_sticks() + + def on_next(self): + if self.busy: + return + if self.page == 0: + self.go(1) + elif self.page == 1: + self.start_scan() + elif self.page == 2: + if self.built: + self.go(3) + else: + self.start_build() + elif self.page == 3: + self.go(4) + elif self.page == 4: + if self.written: + self.go(5) + else: + self._confirm_write() + elif self.page == 5: + self.close() + + def _set_note(self, page): + if page == 0: + self.note.set_text("A guided macOS install for this PC, built from the hardware the check finds.") + elif page == 1: + self.note.set_text("This PC was checked. Continue, or check it again." if self.scanned else + "1401 reads this PC's hardware and firmware tables. Nothing is changed.") + elif page == 2: + self.note.set_text(self.summary.splitlines()[0] if self.built and self.summary else + "Choose the macOS release for this PC, then build and validate the startup files.") + elif page == 3: + self.note.set_text("These BIOS suggestions follow your scan and startup files. Changes here happen by " + "hand in the firmware setup.") + elif page == 4: + self.note.set_text("Plug in the USB stick that will become the macOS installer. Everything on it is " + "erased.") + else: + self.note.set_text("Done. Keep the stick until macOS is installed and running.") + + def _check_engine(self): + report = os.path.join(REPO, "p1401", "scan.py") + if not os.path.isfile(report): + self._message("The engine is missing", + f"p1401 was not found at {REPO}. Run 1401 from the repository, or from the folder the " + "Linux build installed it in.", Gtk.MessageType.ERROR) + self.next.set_sensitive(False) + return False + return False + + def _set_busy(self, busy): + self.busy = busy + for control in self.busy_controls: + control.set_sensitive(not busy) + if busy: + self.next.set_sensitive(False) + self.progress.set_visible(self.page in (1, 2, 4)) + self.progress.set_fraction(0) + self.progress.set_text("Working...") + self._have_progress = False + if self._pulse_id is None: + self._pulse_id = GLib.timeout_add(180, self._pulse) + else: + self.back.set_sensitive(0 < self.page < len(STEPS) - 1) + self.next.set_sensitive(True) + self.progress.set_fraction(0) + self.progress.set_text("") + self.progress.set_visible(False) + if self._pulse_id is not None: + GLib.source_remove(self._pulse_id) + self._pulse_id = None + + def _pulse(self): + if self.busy and not self._have_progress: + self.progress.pulse() + return self.busy + + def _append(self, line): + buffer = self.log_view.get_buffer() + buffer.insert(buffer.get_end_iter(), line + "\n") + self._log_lines += 1 + if self._log_lines > MAX_LOG_LINES: + start = buffer.get_start_iter() + end = buffer.get_iter_at_line(500) + buffer.delete(start, end) + self._log_lines -= 500 + end = buffer.get_end_iter() + self.log_view.scroll_to_iter(end, 0.0, False, 0.0, 0.0) + if self.log_file: + try: + self.log_file.write(line + "\n") + except OSError: + pass + + def _run(self, label, command, done): + if self.busy: + return + self._set_busy(True) + self.last_lines = [] + self._append(f"--- {label} ---") + self._append("$ " + quoted(command)) + env = os.environ.copy() + env["PYTHONUNBUFFERED"] = "1" + env["PYTHONPATH"] = REPO + (os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else "") + + def worker(): + process = None + try: + process = subprocess.Popen(command, cwd=REPO, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, text=True, encoding="utf-8", + errors="replace", bufsize=1, env=env) + for line in process.stdout: + GLib.idle_add(self._line, line.rstrip("\r\n")) + code = process.wait() + except Exception as error: # noqa: BLE001 - shown in the window, not raised out of the thread + GLib.idle_add(self._line, f"Could not run {command[0]}: {error}") + code = 1 + GLib.idle_add(self._finished, code, done) + + threading.Thread(target=worker, daemon=True).start() + + def _line(self, line): + if line.startswith("PROGRESS "): + parts = line.split(" ", 2) + try: + percent = max(0, min(100, int(parts[1]))) + except (IndexError, ValueError): + percent = 0 + self._have_progress = True + self.progress.set_fraction(percent / 100) + self.progress.set_text(parts[2] + f" {percent}%" if len(parts) > 2 else f"{percent}%") + self.last_lines.append(line) + self._append(line) + return False + + def _finished(self, code, done): + self._set_busy(False) + done(code) + return False + + # --- check -------------------------------------------------------------------------------------------------- + + def start_scan(self, force=False): + if self.busy: + return + if self.scanned and not force: + self.go(2) + return + self.scanned = self.built = self.written = False + self.summary = "" + self.guide_file = None + self.scan_id = uuid.uuid4().hex + self.scan_dir = os.path.join(self.work, "scan-" + self.scan_id) + self._clear_log() + self._run("check this PC", interpreter() + ["-m", "p1401.scan", self.scan_dir, "--run-id", self.scan_id], + self._scan_done) + + def _scan_done(self, code): + report = os.path.join(self.scan_dir or "", "Report.json") + if code != 0 or not os.path.isfile(report): + self._message("The check did not finish", + "The lines in the window say why. If the password prompt was dismissed, press Check this " + "PC again and approve it. The log was saved to " + self.log_path, + Gtk.MessageType.ERROR) + return + self.scanned = True + self.load_facts() + self.check_note.set_text("This PC was checked. Continue to build the startup files.") + self.go(1) + self.next.set_label("Continue") + self._save_session() + + def load_facts(self): + while (child := self.facts.get_first_child()) is not None: + self.facts.remove(child) + try: + with open(os.path.join(self.scan_dir, "Report.json"), encoding="utf-8") as fh: + report = json.load(fh) + except (OSError, ValueError) as error: + self._fact("Report", f"could not be read: {error}") + return + board = (report.get("Motherboard") or {}).get("Name") or "unknown board" + cpu = report.get("CPU") or {} + cores = cpu.get("Core Count") or "?" + processor = f"{cpu.get('Processor Name') or 'unknown processor'} ({cores} threads)" + if cpu.get("Manufacturer"): + processor = f"{cpu['Manufacturer']} {processor}" + gpus = list((report.get("GPU") or {}).keys()) + network = list((report.get("Network") or {}).keys()) + drives = list((report.get("Storage Drives") or {}).keys()) + self._fact("Board", board) + self._fact("Processor", processor) + self._fact("Graphics", "; ".join(gpus) if gpus else "none reported") + self._fact("Network", "; ".join(network[:3]) if network else "none reported") + if drives: + self._fact("Storage", "; ".join(drives[:3])) + self._fact("Firmware", f"{(report.get('BIOS') or {}).get('Firmware Type') or 'unknown'}, " + f"Secure Boot {(report.get('BIOS') or {}).get('Secure Boot') or 'unknown'}") + + def _fact(self, name, value): + row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12) + key = Gtk.Label(label=name, xalign=0) + key.set_size_request(110, -1) + key.add_css_class("dim-label") + row.append(key) + text = Gtk.Label(label=value, xalign=0) + text.set_wrap(True) + text.set_selectable(True) + text.set_hexpand(True) + row.append(text) + self.facts.append(row) + + # --- build --------------------------------------------------------------------------------------------------- + + def _chosen_os(self): + index = self.os_pick.get_selected() + if index < 0 or index >= len(OS_CHOICES): + index = 0 + return OS_CHOICES[index] + + def _build_options_changed(self): + if self.busy: + return + was_built = self.built + self.built = False + self.written = False + self.guide_file = None + if was_built: + self.build_summary.set_text("The options changed; build the startup files again.") + self.guide_label.set_text("The steps appear here after a build.") + if self.page == 2: + self.next.set_label("Build") + self.note.set_text("Choose the macOS release for this PC, then build and validate the startup files.") + + def start_build(self): + if self.busy: + return + if not self.scanned: + self.go(1) + return + name, darwin, legacy = self._chosen_os() + self.efi_dir = os.path.join(self.work, "efi") + # The build writes into the same EFI folder and starts with a clean result page. If it fails or the app is + # closed halfway, the previous build is no longer what is on disk, so the session must not offer it. + self.built = self.written = False + self.summary = "" + self.guide_file = None + self.guide_label.set_text("The steps appear here after a build.") + self._save_session() + report = os.path.join(self.scan_dir, "Report.json") + acpi = os.path.join(self.scan_dir, "ACPI") + command = interpreter() + ["-m", "p1401", "build", report, acpi, self.efi_dir, "--json", "--macos", darwin] + if legacy: + command.append("--legacy") + if self.experimental.get_active(): + command.append("--experimental-drivers") + if self.persistent.get_active(): + command.append("--persistent-nvram-amd") + if self.external.get_active(): + command.append("--external-target") + if self.new_identity.get_active(): + command.append("--new-identity") + self._clear_log() + self.build_summary.set_text("") + self._run("build the Mac setup", command, self._build_done) + + def _build_done(self, code): + result = None + start = next((i for i, line in enumerate(self.last_lines) if line.lstrip().startswith("{")), None) + if start is not None: + try: + result = json.JSONDecoder().raw_decode("\n".join(self.last_lines[start:]))[0] + except ValueError: + result = None + if code != 0 or not isinstance(result, dict) or not result.get("ok"): + detail = (result or {}).get("error") or "The lines in the window say why." + self._message("The build stopped", str(detail) + f"\n\nThe full log is in {self.log_path}.", + Gtk.MessageType.ERROR) + return + self.macos_full = str(result.get("macos_version") or "") + self.darwin = self.macos_full.split(".")[0] or self._chosen_os()[1] + name = MACOS_NAMES.get(self.darwin, self.darwin) + self.summary = (f"macOS {name} for this PC, as a {result.get('smbios') or 'Mac'}. The startup files passed " + f"OpenCore's own check.") + for notice in result.get("notices") or []: + if notice and _ACPI_DUMP.search(str(notice)): + continue + self.summary += "\n" + str(notice) + plan = result.get("storage_plan") or {} + if plan.get("steps"): + self.summary += "\n" + ("This PC's drives are behind Intel VMD, which macOS cannot read. Plan:" + if plan.get("kind") == "vmd-off" else + "Install macOS on a drive macOS can see. Plan:") + for index, step in enumerate(plan["steps"], 1): + self.summary += f"\n {index}. {step}" + if plan.get("bios_path"): + self.summary += "\nBIOS: " + str(plan["bios_path"]) + for change in result.get("policy_changes") or []: + if change.get("rule") == "known-machine": + self.summary += f"\nSetting known to work on this processor: {change.get('after')} ({change.get('why')})" + elif change.get("rule") == "usb-map-import": + self.summary += f"\nUSB port map: {change.get('after')} ({change.get('why')})" + self.build_summary.set_text(self.summary) + self.built = True + self.written = False + self._save_session() + self._make_guide() + + def _make_guide(self): + report = os.path.join(self.scan_dir, "Report.json") + config = os.path.join(self.efi_dir, "EFI", "OC", "config.plist") + guide = os.path.join(self.work, "BIOS-steps.html") + self._run("write the BIOS steps", + interpreter() + ["-m", "p1401.guide", report, config, "--macos", self.macos_full, "--html", guide], + lambda code: self._guide_done(code, guide)) + + def _guide_done(self, code, guide): + if code == 0 and os.path.isfile(guide): + self.guide_file = guide + self.guide_label.set_text(guide) + else: + self._message("The BIOS steps could not be written", + "The startup files are built and valid. The BIOS page is missing; check the log and press " + "Open the BIOS steps to try again.", Gtk.MessageType.WARNING) + self._save_session() + self.go(2) + self.next.set_label("Continue") + + def show_guide(self): + if not self.guide_file or not os.path.isfile(self.guide_file): + if self.built: + self._make_guide() + return + try: + Gio.AppInfo.launch_default_for_uri(GLib.filename_to_uri(self.guide_file, None), None) + except GLib.Error as error: + self._message("Could not open the guide", str(error), Gtk.MessageType.ERROR) + + # --- stick --------------------------------------------------------------------------------------------------- + + def fill_sticks(self): + if self.busy: + return + try: + disks = linuxusb.list_disks() + except linuxusb.UsbError as error: + self.usb_disks = [] + self.stick_drop.set_model(Gtk.StringList.new(["Could not list disks"])) + self.stick_info.set_text(str(error)) + return + usable = [] + for disk in disks: + if disk.get("BusType") != "USB" or disk.get("IsSystem") or disk.get("IsReadOnly"): + continue + if int(disk.get("Size") or 0) < linuxusb.MIN_DISK: + continue + usable.append(disk) + self.usb_disks = usable + labels = [f"{linuxusb.stick_name(d)} - {d['Path']}" for d in usable] + if not labels: + labels = ["No USB stick found - plug one in and press Refresh"] + self.stick_drop.set_model(Gtk.StringList.new(labels)) + self.stick_drop.set_selected(0) + self._stick_changed() + + def _chosen_stick(self): + index = self.stick_drop.get_selected() + if index < 0 or index >= len(self.usb_disks): + return None + return self.usb_disks[index] + + def _stick_changed(self): + disk = self._chosen_stick() + if disk is None: + self.stick_info.set_text("Plug in a USB stick that can be erased. Internal disks are never offered.") + return + text = f"{disk['FriendlyName']}, {linuxusb.size_text(disk['Size'])}, {disk['Path']}" + if disk["Size"] > linuxusb.MAX_DISK: + text += ". This is larger than a normal USB stick; 1401 asks once more before erasing a drive this size." + if self.full_installer.get_active() and disk["Size"] < 32 * linuxusb.GiB: + text += ". The full installer needs a stick of 32 GB or more." + self.stick_info.set_text(text) + + def pick_recovery(self): + # Gtk.FileChooserNative rather than Gtk.FileDialog: the latter arrived in GTK 4.10 and Debian 12 ships 4.8. + dialog = Gtk.FileChooserNative(title="Folder with BaseSystem.dmg and BaseSystem.chunklist", + transient_for=self, action=Gtk.FileChooserAction.SELECT_FOLDER, + accept_label="Use this folder", cancel_label="Cancel") + dialog.connect("response", self._recovery_chosen) + dialog.show() + + def _recovery_chosen(self, dialog, response): + try: + if response == Gtk.ResponseType.ACCEPT: + folder = dialog.get_file() + path = folder.get_path() if folder else None + if path: + self.recovery_dir = path + self.recovery_label.set_text(path) + finally: + dialog.destroy() + + def _confirm_write(self): + disk = self._chosen_stick() + if disk is None: + self._message("No USB stick", "Plug in a USB stick, press Refresh, and pick it from the list.", + Gtk.MessageType.INFO) + return + ok, why = linuxusb.eligible(disk, allow_large=True) + if not ok: + self._message("This stick cannot be used", "; ".join(why), Gtk.MessageType.ERROR) + return + if disk["Size"] > linuxusb.MAX_DISK and not self._ask( + "A very large USB drive", + f"{linuxusb.stick_name(disk)} is larger than any USB stick 1401 expects. A drive this big is usually " + "a backup disk. Erase it anyway?", "Use this drive"): + return + if self.full_installer.get_active(): + if self.darwin not in ("24", "25"): + self._message("The full installer is not available for this release", + "Apple publishes the full installer for macOS 15 and macOS 26 only. Turn the option off " + "for an older release.", Gtk.MessageType.INFO) + return + if disk["Size"] < 32 * linuxusb.GiB: + self._message("The stick is too small for the full installer", + "The full installer needs a stick of 32 GB or more. Pick a larger stick or turn the " + "option off.", Gtk.MessageType.INFO) + return + if not self._ask("Erase this stick?", + f"{linuxusb.stick_name(disk)} will become the macOS installer. Everything on it will be " + "lost.", "Erase and create"): + return + if not self.full_installer.get_active(): + self.full_pkg = None + self._prepare_driver() + + def _prepare_driver(self): + if not os.path.isfile(os.path.join(self.efi_dir, "EFI", "OC", "config.plist")): + self._message("The startup files are missing", + "Build the Mac setup again, then return to this page. The stick was not touched.", + Gtk.MessageType.ERROR) + return + self._clear_log() + self._run("check the NVIDIA driver packages", + interpreter() + ["-m", "p1401.linuxusb", "prepare-driver", self.efi_dir], + self._driver_done) + + def _driver_done(self, code): + if code != 0: + self._message("The driver package could not be prepared", + "The stick was not touched. Check the connection and try again; the log says which " + "download failed.", Gtk.MessageType.ERROR) + return + if self.full_installer.get_active(): + self._fetch_full_installer() + else: + self.start_write() + + def _fetch_full_installer(self): + folder = os.path.join(self.work, "full-installer", self.darwin) + package = os.path.join(folder, "InstallAssistant.pkg") + if os.path.isfile(package): + self.full_pkg = package + self._append(f"Using the full installer already downloaded at {package}") + self.start_write() + return + os.makedirs(folder, exist_ok=True) + self._clear_log() + self._run("download the full macOS installer", + interpreter() + ["-m", "p1401.fullinstaller", "fetch", self.darwin, folder], + lambda code: self._full_installer_done(code, package)) + + def _full_installer_done(self, code, package): + if code != 0 or not os.path.isfile(package): + self._message("The full installer could not be downloaded", + "The stick was not touched. Turn the option off to write the usual online installer, or " + "check the connection and try again.", Gtk.MessageType.ERROR) + return + self.full_pkg = package + self.start_write() + + def start_write(self, erase_os=False): + disk = self._chosen_stick() + if disk is None: + self.fill_sticks() + return + # linuxroot.py usb takes the writer's own arguments (write ...), not the `python -m` part: pkexec runs the + # root helper with this list, while an already-root app runs the module directly. + args = ["write", disk["Path"], self.efi_dir, self.darwin, + "--profile", os.path.join(self.scan_dir, "Report.json"), + "--stick-id", disk.get("UniqueId") or "", + "--stick-size", str(disk["Size"]), + "--stick-name", disk.get("FriendlyName") or "", + "--recovery-dir", self.recovery_dir] + if disk["Size"] > linuxusb.MAX_DISK: + args.append("--allow-large") + if self.full_pkg: + args += ["--full-installer", self.full_pkg] + if erase_os: + args.append("--erase-os-partitions") + if os.geteuid() == 0: + elevated = interpreter() + ["-m", "p1401.linuxusb"] + args + else: + pkexec = shutil.which("pkexec") + if not pkexec: + self._message("policykit is missing", + "Writing a USB stick needs root, and pkexec was not found. Install polkit, or run " + "1401 from a root terminal.", Gtk.MessageType.ERROR) + return + elevated = [pkexec, sys.executable, os.path.join(REPO, "p1401", "linuxroot.py"), "usb"] + args + self._clear_log() + self._run("create the macOS stick", elevated, + lambda code: self._write_done(code, erase_os)) + + def _write_done(self, code, erase_os): + if code == 0: + self.written = True + self.built = True + self.go(5) + return + held = next((line for line in self.last_lines if "1401-OS-PARTITIONS:" in line), None) + if held and not erase_os: + detail = held.split("1401-OS-PARTITIONS:", 1)[1].strip() + if self._ask("This stick is not empty", + f"It holds {detail}\n\nThat is usually an old macOS installer, but it can also be a Mac " + "backup or a system. Erase it anyway?", "Erase it anyway"): + self.start_write(erase_os=True) + return + if any("1401-DISK-RENUMBERED" in line for line in self.last_lines): + self.fill_sticks() + stop = next((line[5:].strip() for line in reversed(self.last_lines) if line.startswith("STOP ")), "") + detail = (stop + "\n\n" if stop else "The lines in the window say why. ") + ( + "The stick may be partly written. The log is saved to " + self.log_path) + self._message("Writing the stick did not finish", detail, Gtk.MessageType.ERROR) + + # --- small dialogs ------------------------------------------------------------------------------------------- + + def _message(self, title, detail, kind=Gtk.MessageType.INFO): + dialog = Gtk.MessageDialog(transient_for=self, modal=True, message_type=kind, + buttons=Gtk.ButtonsType.OK, text=title) + dialog.set_property("secondary-text", detail) + loop = GLib.MainLoop() + + def response(d, _r): + d.destroy() + loop.quit() + dialog.connect("response", response) + dialog.present() + loop.run() + + def _ask(self, title, detail, ok_label="Continue"): + dialog = Gtk.MessageDialog(transient_for=self, modal=True, message_type=Gtk.MessageType.WARNING, + buttons=Gtk.ButtonsType.NONE, text=title) + dialog.set_property("secondary-text", detail) + dialog.add_button("Cancel", Gtk.ResponseType.CANCEL) + dialog.add_button(ok_label, Gtk.ResponseType.OK) + dialog.set_default_response(Gtk.ResponseType.CANCEL) + answer = {"ok": False} + loop = GLib.MainLoop() + + def response(d, result): + answer["ok"] = result == Gtk.ResponseType.OK + d.destroy() + loop.quit() + dialog.connect("response", response) + dialog.present() + loop.run() + return answer["ok"] + + def _clear_log(self): + self.log_view.get_buffer().set_text("") + self._log_lines = 0 + + def _on_close(self, _window): + if self.busy: + self._message("1401 is still working", + "Wait for the current step to finish. Closing the window in the middle of a USB write can " + "leave the stick half erased.", Gtk.MessageType.WARNING) + return True + try: + self.log_file.close() + except OSError: + pass + return False + + +class App(Gtk.Application): + def __init__(self, selftest=False): + flags = Gio.ApplicationFlags.DEFAULT_FLAGS + if selftest: + flags |= Gio.ApplicationFlags.NON_UNIQUE + super().__init__(application_id="com.nullmothsystems.FourteenOhOne", flags=flags) + self.window = None + self.selftest = selftest + self.selftest_ok = True + + def do_activate(self): + if self.window is None: + self.window = Window(self) + if self.selftest: + GLib.idle_add(self._selftest) + return + self.window.present() + else: + self.window.present() + + def _selftest(self): + """Build every page without touching hardware, then leave. Run with a display; no scan, no disk write.""" + try: + for page in range(len(STEPS)): + self.window.go(page) + shown = self.window.stack.get_visible_child_name() + if shown != f"page{page}": + raise RuntimeError(f"page {page} is not the visible page ({shown})") + self.window.go(0) + self.window.on_next() + if self.window.page != 1: + raise RuntimeError("Get started did not lead to the check") + self.window.go(3) + self.window.on_next() + if self.window.page != 4: + raise RuntimeError("the BIOS page did not lead to the stick") + self.window.go(0) + print("selftest: all pages built", flush=True) + except Exception as error: # noqa: BLE001 - the exit status carries the failure + print(f"selftest: {type(error).__name__}: {error}", file=sys.stderr, flush=True) + self.selftest_ok = False + self.quit() + return False + self.quit() + return False + + +def main(): + args = [arg for arg in sys.argv if arg != "--selftest"] + selftest = len(args) != len(sys.argv) + os.makedirs(state_dir(), exist_ok=True) + app = App(selftest) + status = app.run(args) + if selftest and not app.selftest_ok: + return 1 + return status + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/linux/README.md b/linux/README.md new file mode 100644 index 00000000..6433a51f --- /dev/null +++ b/linux/README.md @@ -0,0 +1,98 @@ +# 1401 on Linux + +The Linux window does the same four steps as the Windows app: Check this PC, Build the Mac setup, Your BIOS steps, and +Create the macOS stick. It is GTK 4 on top of the same Python engine, so the rules, downloads and checks are the ones +described in `docs/HOW-IT-WORKS.md`, not a second implementation. + +The Linux app is newer than the Windows one. The engine steps are tested, but the window and the stick writer have not +been through as many real installs. Treat the first stick you write as a test. + +## Packages + +Debian and Ubuntu: + +```bash +sudo apt install python3-gi gir1.2-gtk-4.0 policykit-1 dosfstools exfatprogs +``` + +Fedora: + +```bash +sudo dnf install python3-gobject gtk4 polkit dosfstools exfatprogs +``` + +Arch: + +```bash +sudo pacman -S python-gobject gtk4 polkit dosfstools exfatprogs +``` + +`util-linux`, `systemd` and `pciutils` are already part of a normal desktop install and provide `lsblk`, `mount`, +`udevadm`, `lspci` and `blockdev`. `exfatprogs` is only needed for the optional full installer; without it the online +installer still works. `partprobe` from `parted` is used when present, and skipped otherwise. + +The window runs as your user. Two steps ask policykit for root: + +- the hardware check reads `/sys/firmware/acpi/tables`, which only root may open; +- writing the stick erases the disk, formats it and mounts it. + +`pkexec` shows the usual password dialog. The app never runs the whole window as root. + +## Running it + +From the checkout: + +```bash +python3 linux/1401.py +``` + +or `linux/1401`. To make a folder that can be moved out of the checkout: + +```bash +bash linux/build.sh # writes dist/1401-linux +dist/1401-linux/1401 +``` + +The build runs the writer tests and a window self-test first, then copies the engine, `upstream/`, `vendor/` and the +window. It does not download OpenCore; the first build does that, into the copy's `upstream/` folder. + +`dist/1401-linux/1401.desktop` points at the staged launcher. Copy it to `~/.local/share/applications` if you want a +menu entry. + +## What it writes + +The stick gets a new MBR with a FAT32 partition labelled `1401`, the OpenCore EFI, and Apple's recovery image under +`com.apple.recovery.boot/`. The image is downloaded from Apple after the stick is erased and checked chunk by chunk +against Apple's signed chunklist. The EFI is copied and read back. + +The full installer option needs a stick of 32 GB or more and a download of Apple's `InstallAssistant.pkg`. The package +is checked with `xar` before anything is written, then unpacked onto a second exFAT partition labelled `NMINSTALL`. +Without the option, macOS downloads the rest itself after the installer starts. + +Only USB disks are offered. A disk with `/`, `/boot`, `/home` or another system directory mounted on it is refused by +both the window and the writer, and a disk still held open by LUKS, LVM or RAID is refused until that layer is closed. +The writer looks the stick up again by serial, size and model before erasing it, so a stick that came back as +`/dev/sdc` cannot be confused with another disk. A stick that holds an APFS, HFS+, Windows recovery or Linux partition +is reported before it is erased; the window asks once more. + +The NVIDIA driver packages are downloaded by the user's process before the elevated write, so the build folder does not +end up with root-owned files. + +## Where things are kept + +- scans, the built EFI and the BIOS page: `$XDG_STATE_HOME/nullmoth/1401/` (usually `~/.local/state/nullmoth/1401`); +- a recovery image you picked by hand: `$XDG_DATA_HOME/nullmoth/1401/Recovery/` (usually + `~/.local/share/nullmoth/1401/Recovery`); +- the log: `$XDG_STATE_HOME/nullmoth/1401/1401.log`, also shown in the window. + +Nothing is uploaded. The Linux window has no log-upload step; the log and the scan folder stay on this PC. + +## Tests + +```bash +python3 -m unittest tests.test_linux_usb tests.test_linux_root +python3 linux/1401.py --selftest # needs a display; builds every page and exits +python3 -m unittest discover -s tests -t . -p 'test_*.py' +``` + +The writer tests use fake `lsblk` output and a fake ACPI tree. They never touch a disk. diff --git a/linux/build.sh b/linux/build.sh new file mode 100755 index 00000000..f1f234fe --- /dev/null +++ b/linux/build.sh @@ -0,0 +1,41 @@ +#!/bin/bash +# Stages a folder that runs without the rest of the checkout: the engine, the pinned upstream copies it needs, and the +# GTK window. The engine is Python, so nothing is compiled; this is a copy plus a launcher. +set -euo pipefail +cd "$(dirname "$0")/.." + +OUT=${1:-dist/1401-linux} +mkdir -p "$(dirname "$OUT")" +OUT=$(realpath -m "$OUT") + +python3 -m unittest tests.test_linux_usb tests.test_linux_root \ + || { echo "STOP: the Linux stick writer tests failed"; exit 1; } + +if [ -n "${DISPLAY:-}${WAYLAND_DISPLAY:-}" ]; then + python3 linux/1401.py --selftest || { echo "STOP: the window could not build its pages"; exit 1; } +else + echo "note: no display, skipped the window self-test" +fi + +rm -rf "$OUT" +mkdir -p "$OUT" +cp -a p1401 upstream vendor linux "$OUT/" +rm -f "$OUT/linux/1401.desktop" # the staged copy gets one with an absolute Exec below +find "$OUT" -name __pycache__ -type d -prune -exec rm -rf {} + +rm -rf "$OUT/upstream/OpCore-Simplify/OCK_Files" "$OUT/upstream/OpCore-Simplify/Results" +cp LICENSE NOTICE.md README.md "$OUT/" + +cat > "$OUT/1401" <<'LAUNCHER' +#!/bin/sh +# Starts 1401 from the folder this script is in. The engine downloads OpenCore and the kexts into upstream/ on first use. +set -eu +here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +exec python3 -u "$here/linux/1401.py" "$@" +LAUNCHER +chmod 755 "$OUT/1401" + +case $OUT in + *[[:space:]]*) echo "STOP: the output path has a space, which a desktop entry cannot express"; exit 1 ;; +esac +sed "s|@EXEC@|$OUT/1401|" linux/1401.desktop > "$OUT/1401.desktop" +echo "built $OUT" diff --git a/p1401/linuxroot.py b/p1401/linuxroot.py new file mode 100644 index 00000000..0f609f84 --- /dev/null +++ b/p1401/linuxroot.py @@ -0,0 +1,158 @@ +"""The two steps of the Linux app that need root: reading the firmware's ACPI tables, and writing a USB stick. + +The app runs as the user. ACPI tables under /sys/firmware/acpi/tables are readable by root only, so the scan asks +policykit to run this file's `acpi` command once. The USB writer is started the same way (`usb write ...`) so the +whole erase, format and mount sequence happens in one elevated process rather than a mix of sudo calls. + + pkexec python3 p1401/linuxroot.py acpi --owner UID:GID + pkexec python3 p1401/linuxroot.py usb write [options] + +When the app itself is already root (a root shell, a live session) the same functions are called directly. +""" +import os +import shutil +import subprocess +import sys + +REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +TABLES = "/sys/firmware/acpi/tables" +SYSTEM_ACPI = ("DSDT", "FACP", "FACS", "APIC", "MCFG", "HPET", "SRAT", "SLIT", "XSDT", "RSDT") + + +class RootError(RuntimeError): + pass + + +def _destination(relative): + """sysfs names one table `DSDT`; the builder expects `DSDT.aml`. Subdirectories (dynamic/) stay subdirectories.""" + return os.path.join(*[part.upper() for part in relative.split(os.sep)]) + ".aml" + + +def copy_tables(source=TABLES, dest=None, owner=None): + """Copies every table under `source` into `dest`, returns the paths written. + + Reads are done as root and each file is made readable by its owner before the scan continues as the user. A + table that vanishes between listdir and open is skipped: hot-plugged Thunderbolt boxes can add and remove SSDTs + while the scan runs, and one missing optional table should not lose the DSDT. + """ + if not dest: + raise RootError("no destination for the ACPI tables") + if not os.path.isdir(source): + raise RootError(f"{source} does not exist: this kernel has no ACPI table directory") + written = [] + for folder, folders, names in os.walk(source, followlinks=False): + folders.sort() + rel_dir = os.path.relpath(folder, source) + for name in sorted(names): + src = os.path.join(folder, name) + if os.path.islink(src) or not os.path.isfile(src): + continue + relative = name if rel_dir == "." else os.path.join(rel_dir, name) + dst = os.path.join(dest, _destination(relative)) + os.makedirs(os.path.dirname(dst), exist_ok=True) + try: + with open(src, "rb") as source_file: + data = source_file.read() + except FileNotFoundError: + continue + with open(dst + ".tmp", "wb") as out: + out.write(data) + os.replace(dst + ".tmp", dst) + os.chmod(dst, 0o644) + if owner: + os.chown(dst, owner[0], owner[1]) + written.append(dst) + if not table_has(os.path.join(dest, "DSDT.aml"), b"DSDT"): + raise RootError(f"the ACPI directory {source} had no DSDT; this PC's firmware tables cannot be read") + return written + + +def table_has(path, signature): + try: + with open(path, "rb") as fh: + return fh.read(4) == signature + except OSError: + return False + + +def _owner(value): + if not value: + return None + try: + uid, gid = value.split(":", 1) + return int(uid), int(gid) + except ValueError as error: + raise RootError(f"bad --owner {value!r}; expected UID:GID") from error + + +def _write_acpi(dest, owner): + if os.geteuid() != 0: + raise RootError("reading /sys/firmware/acpi/tables needs root") + tables = copy_tables(dest=dest, owner=owner) + print(f"copied {len(tables)} ACPI table(s) to {dest}", flush=True) + return 0 + + +def elevate_acpi(dest): + """Runs the ACPI copy through pkexec, or directly when the process is already root. Returns the child's output. + + pkexec exits 126 when the password dialog is dismissed and 127 when no agent answers; both mean the scan + cannot see the firmware, so they get one sentence instead of an exit code. + """ + owner = f"{os.getuid()}:{os.getgid()}" + if os.geteuid() == 0: + _write_acpi(dest, None) + return + tool = shutil.which("pkexec") + if not tool: + raise RootError("pkexec is not installed. Install policykit-1/polkit, or run 1401 from a root terminal.") + command = [tool, sys.executable, os.path.join(REPO, "p1401", "linuxroot.py"), "acpi", dest, "--owner", owner] + result = subprocess.run(command, capture_output=True, text=True, timeout=300) + if result.returncode != 0: + detail = " ".join((result.stderr or result.stdout or "").split())[-500:] + if result.returncode in (126, 127): + raise RootError("the ACPI read was not authorised, so the hardware check cannot finish. Approve the " + "password prompt and run Check this PC again.") + raise RootError(f"copying the ACPI tables failed (pkexec exit {result.returncode}): {detail or 'no detail'}") + if result.stdout: + print(result.stdout.rstrip(), flush=True) + + +def main(argv=None): + argv = list(sys.argv[1:] if argv is None else argv) + if not argv: + print("usage: linuxroot.py acpi --owner UID:GID | usb ...", file=sys.stderr) + return 2 + command, rest = argv[0], argv[1:] + try: + if command == "acpi": + dest, owner = None, None + i = 0 + while i < len(rest): + if rest[i] == "--owner" and i + 1 < len(rest): + owner = _owner(rest[i + 1]) + i += 2 + continue + if dest is None: + dest = rest[i] + i += 1 + if not dest: + raise RootError("acpi needs a destination directory") + return _write_acpi(dest, owner) + if command == "usb": + from p1401 import linuxusb # noqa: PLC0415 - the writer imports the engine only when it is used + return linuxusb.main(rest) + except RootError as error: + print(f"STOP {error}", file=sys.stderr) + return 1 + print(f"unknown command {command!r}", file=sys.stderr) + return 2 + + +if __name__ == "__main__": + if not __package__: + # pkexec starts this file by path, so make `p1401` importable before reloading it under its real name. + sys.path.insert(0, REPO) + from p1401 import linuxroot # noqa: PLC0415 + sys.exit(linuxroot.main()) + sys.exit(main()) diff --git a/p1401/linuxusb.py b/p1401/linuxusb.py new file mode 100644 index 00000000..59ae3063 --- /dev/null +++ b/p1401/linuxusb.py @@ -0,0 +1,697 @@ +"""Writes the 1401 installer USB on Linux. + +Same layout as the Windows writer: an MBR disk with one small FAT32 partition carrying EFI/ and +com.apple.recovery.boot/. The macOS image is downloaded from Apple and checked chunk by chunk, the EFI is copied and +read back, and the optional full installer gets a second exFAT partition. The Windows module still owns the payload +stage; this one does the disk work with Linux' own tools. + +The destructive part is deliberately small: the partition table is replaced through the block device, then mkfs.vfat +formats the new partition. Nothing here calls parted or sfdisk, because both change their command lines between the +versions that ship on LTS distributions. + + python3 -m p1401.linuxusb list + python3 -m p1401.linuxusb write /dev/sdX 24 [options] + +Everything below `write` runs as root, normally through `pkexec p1401/linuxroot.py usb ...`. The list command does not: +it only reads lsblk and /dev/disk/by-id. +""" +import json +import os +import shutil +import stat +import struct +import subprocess +import sys +import tempfile +import time + +GiB = 1 << 30 +MiB = 1 << 20 +MIN_DISK = 2 * GiB +MAX_DISK = 256 * GiB +PART_CAP = 16 * GiB +LABEL = "1401" +SECOND_LABEL = "NMINSTALL" +FAT32_LBA = 0x0C +EXFAT = 0x07 +MBR_BOOT = 0x80 + +APPLE_APFS = "7c3457ef-0000-11aa-aa11-00306543ecac" +APPLE_HFS = "48465300-0000-11aa-aa11-00306543ecac" +WINDOWS_RECOVERY = "de94bba4-06d1-4d40-a16a-bfd50179d6ac" +LINUX_FS_GUID = "0fc63daf-8483-4772-8e79-3d69d8477de4" + +SYSTEM_ROOTS = ("/", "/boot", "/boot/efi", "/home", "/usr", "/etc", "/var", "/opt", "/srv", "/root", "/nix", "/snap") +BUS_NAMES = {"usb": "USB", "sata": "SATA", "ata": "ATA", "nvme": "NVMe", "mmc": "MMC", "sd": "SD", "sas": "SAS"} + +RECOVERY_DIR = os.path.join(os.environ.get("XDG_DATA_HOME") or os.path.join(os.path.expanduser("~"), ".local", "share"), + "nullmoth", "1401", "Recovery") + + +class UsbError(RuntimeError): + pass + + +def _run(command, timeout=120, check=True): + try: + p = subprocess.run(command, capture_output=True, text=True, timeout=timeout) + except FileNotFoundError: + raise UsbError(f"{command[0]} is not installed") from None + except subprocess.TimeoutExpired: + raise UsbError(f"{command[0]} did not finish within {timeout} seconds") from None + if check and p.returncode != 0: + detail = " ".join((p.stderr or p.stdout or "").split())[-500:] + raise UsbError(f"{' '.join(command)} failed: {detail or f'exit {p.returncode}'}") + return p + + +def size_text(value): + if value >= GiB: + return f"{value / GiB:.0f} GB" if value >= 10 * GiB else f"{value / GiB:.1f} GB" + return f"{value / (1 << 20):.0f} MB" + + +def _sha256(path, block=1 << 20): + import hashlib # noqa: PLC0415 + digest = hashlib.sha256() + with open(path, "rb") as fh: + for chunk in iter(lambda: fh.read(block), b""): + digest.update(chunk) + return digest.hexdigest() + + +def prepare_driver(efi_build_dir, say=print): + """Download the pinned NVIDIA packages into the build's cache while still the user. + + The writer itself may run as root; if it fetched these, the build folder would end up with root-owned files and + the next ordinary build could not clear it. Returns the paths prepared (empty when this build needs no driver). + An experimental target has a kit per macOS release instead of the 15/26 package. + """ + from . import legacy, nullmoth, usbwriter # noqa: PLC0415 + if not usbwriter.needs_nullmoth(efi_build_dir): + say("OK no NVIDIA driver package is needed for this build") + return [] + older = legacy.read_marker(efi_build_dir) + if older: + package = legacy.kit(older) + if not package.get("sha256"): + raise UsbError(f"the NVIDIA driver kit for {legacy.NAME[older]} has no pinned SHA-256 yet, so 1401 will " + "not put an unchecked package on the stick") + packages = [package] + else: + packages = [nullmoth.PACKAGE, nullmoth.FIRMWARE_RUN] + cache = os.path.join(efi_build_dir, ".cache") + os.makedirs(cache, exist_ok=True) + prepared = [] + for package in packages: + target = os.path.join(cache, package["name"]) + if os.path.isfile(target) and _sha256(target) == package["sha256"]: + say(f"OK {package['name']} is already downloaded and checked") + prepared.append(target) + continue + say(f"STEP downloading {package['name']}") + part = target + ".part" + if os.path.exists(part): + os.remove(part) + try: + usbwriter._fetch(package["url"], part) + except Exception as error: # noqa: BLE001 - the mirror is the second chance the writer uses too + mirror = nullmoth.mirror_of(package["url"]) + if not mirror: + raise UsbError(f"could not download {package['name']}: {error}") from None + say(f"(GitHub download failed: {error}; trying the NullMoth mirror)") + usbwriter._fetch(mirror, part) + if _sha256(part) != package["sha256"]: + os.remove(part) + raise UsbError(f"{package['name']} does not match its pinned SHA-256 - nothing will be put on the stick") + os.replace(part, target) + _give_back(target, efi_build_dir) + say(f"OK downloaded and checked {package['name']}") + prepared.append(target) + return prepared + + +def _mountpoints(part): + raw = part.get("mountpoints") + if raw is None: + # util-linux before 2.37 has no MOUNTPOINTS column and calls it MOUNTPOINT instead. + raw = [part.get("mountpoint")] if part.get("mountpoint") else [] + return [p for p in raw if p and not p.startswith("[")] + + +def _system_mount(path): + # "/" is a root of its own; matching every absolute path against it would make every mounted stick a system disk. + return any(path == root or (root != "/" and path.startswith(root.rstrip("/") + "/")) for root in SYSTEM_ROOTS) + + +def _nodes(block): + for node in block or []: + yield node + yield from _nodes(node.get("children")) + + +def _block_devices(): + columns = "NAME,PATH,TYPE,SIZE,RO,RM,TRAN,MODEL,SERIAL,VENDOR,ROTA,MOUNTPOINTS,PARTTYPE,FSTYPE,LABEL" + command = ["lsblk", "-J", "-b", "-o", columns] + try: + p = _run(command, timeout=30) + except UsbError: + # MOUNTPOINTS arrived in util-linux 2.37. A distribution still on 2.36 answers "unknown column"; the single + # MOUNTPOINT it does have is enough to recognise the running system's disk. + p = _run(["lsblk", "-J", "-b", "-o", columns.replace("MOUNTPOINTS", "MOUNTPOINT")], timeout=30) + try: + return json.loads(p.stdout or "{}").get("blockdevices") or [] + except ValueError as error: + raise UsbError(f"lsblk returned something other than JSON ({error})") from None + + +def _identity_links(device): + folder = "/dev/disk/by-id" + try: + names = os.listdir(folder) + except OSError: + return [] + found = [] + for name in names: + path = os.path.join(folder, name) + try: + if os.path.realpath(path) == os.path.realpath(device): + found.append(name) + except OSError: + continue + return sorted(found) + + +def _disk(node): + name = (node.get("name") or "").strip() + device = (node.get("path") or ("/dev/" + name)).strip() + model = " ".join(x for x in ((node.get("vendor") or "").strip(), (node.get("model") or "").strip()) if x) + bus = BUS_NAMES.get((node.get("tran") or "").lower(), (node.get("tran") or "unknown").upper()) + parts = [] + for child in node.get("children") or []: + if (child.get("type") or "") != "part": + continue + parts.append({"Path": child.get("path") or ("/dev/" + (child.get("name") or "")), + "Size": int(child.get("size") or 0), + "FSType": (child.get("fstype") or "").lower(), + "PartType": (child.get("parttype") or "").lower(), + "Label": child.get("label") or "", + "Mountpoints": _mountpoints(child)}) + mounts = [m for child in _nodes(node.get("children")) for m in _mountpoints(child)] + system = any(_system_mount(m) for m in mounts) + stacked = [{"Name": child.get("name") or "", "Type": child.get("type") or ""} + for child in _nodes(node.get("children")) if (child.get("type") or "") not in ("part", "disk")] + links = _identity_links(device) + uid = (node.get("serial") or "").strip() + if not uid: + uid = next((n for n in links if not n.startswith("wwn-")), device) + return {"Number": 0, "Path": device, "Name": name, "FriendlyName": model or name or device, + "SerialNumber": (node.get("serial") or "").strip(), "UniqueId": uid, "BusType": bus, + "Size": int(node.get("size") or 0), "IsBoot": system, "IsSystem": system, + "IsOffline": False, "IsReadOnly": bool(node.get("ro")), + "Removable": bool(node.get("rm")), "Rotational": bool(node.get("rota")), + "Partitions": parts, "Mountpoints": mounts, "Byid": links, "PartitionStyle": "unknown", + "Stacked": stacked} + + +def list_disks(): + """Every whole disk lsblk reports, system disk included. The GUI and eligibility() decide what is writable.""" + disks = [] + for node in _block_devices(): + if (node.get("type") or "") != "disk": + continue + if (node.get("name") or "").startswith("zram"): + continue + disk = _disk(node) + disk["Number"] = len(disks) + disks.append(disk) + return disks + + +def storage_rows(): + """The scan's Storage Drives section, shaped like the Windows Get-Disk rows.""" + rows = [] + for disk in list_disks(): + rows.append({"Number": disk["Number"], "Model": disk["FriendlyName"], "BusType": disk["BusType"], + "MediaType": "SSD" if not disk["Rotational"] else "HDD", "Size": disk["Size"], + "IsBoot": disk["IsBoot"], "IsSystem": disk["IsSystem"]}) + return rows + + +def stick_name(disk): + return f"{disk.get('FriendlyName') or 'the USB stick'} ({size_text(int(disk.get('Size') or 0))})" + + +def eligible(disk, allow_large=False): + """Every reason this disk cannot be erased, worded for the person who picked it.""" + why = [] + if disk.get("BusType") != "USB": + why.append(f"not a USB disk (bus: {disk.get('BusType')})") + if disk.get("IsSystem"): + why.append("this disk holds the running system's partitions") + if disk.get("IsReadOnly"): + why.append("the stick is read-only (check the lock switch, or use another stick)") + if disk.get("Stacked"): + kinds = sorted({str(item.get("Type") or "device") for item in disk["Stacked"]}) + why.append(f"Linux is still using this disk through {', '.join(kinds)}; close or unlock that first") + size = int(disk.get("Size") or 0) + if size < MIN_DISK: + why.append(f"too small ({size / GiB:.1f} GB; the installer needs 2)") + if size > MAX_DISK and not allow_large: + why.append(f"{size / GiB:.0f} GB is larger than a USB stick 1401 expects - confirm it is not a backup drive") + return not why, why + + +def os_partitions(disk): + """What on this stick looks like an operating system, as short labels. Empty for a normal installer stick.""" + found = [] + for part in disk.get("Partitions") or []: + kind = part.get("PartType") or "" + fstype = part.get("FSType") or "" + label = "" + if kind == APPLE_APFS or fstype == "apfs": + label = "Mac APFS" + elif kind == APPLE_HFS or fstype in ("hfsplus", "hfs"): + label = "Mac HFS+" + elif kind == WINDOWS_RECOVERY: + label = "Windows recovery" + elif kind == LINUX_FS_GUID or fstype in ("ext2", "ext3", "ext4", "btrfs", "xfs", "f2fs", "zfs_member", + "crypto_luks", "lvm2_member"): + label = "Linux" + if label: + found.append(f"{label} {size_text(int(part.get('Size') or 0))}") + return found + + +def find_same(disks, uid, size, name, path=None): + """The stick that was picked, found again by what it is instead of the device node it had. + + USB storage can come back as /dev/sdc after a replug, and a different stick can take /dev/sdb. The serial is + checked first; controllers that invent a new serial on every read fall back to size and model, and only when + exactly one USB disk matches. `path` is the last resort for a stick with neither a serial nor a model. + """ + uid = (uid or "").strip() + if uid: + hit = [d for d in disks if (d.get("UniqueId") or "").strip() == uid] + if len(hit) == 1: + return hit[0] + want = int(size or -1) + hit = [d for d in disks if d.get("BusType") == "USB" and int(d.get("Size") or 0) == want + and (d.get("FriendlyName") or "").strip() == (name or "").strip()] + if len(hit) == 1: + return hit[0] + if path: + hit = [d for d in disks if d.get("Path") == path and int(d.get("Size") or 0) == want + and (d.get("FriendlyName") or "").strip() == (name or "").strip()] + return hit[0] if len(hit) == 1 else None + + +def partition_path(device, number=1): + """sda1, but nvme0n1p1 and mmcblk0p1: the kernel adds p after a name that ends in a digit.""" + return device + ("p" if device[-1:].isdigit() else "") + str(int(number)) + + +def _chs(lba): + heads, sectors = 255, 63 + cylinder, rest = divmod(lba, heads * sectors) + if cylinder > 1023: + return b"\xfe\xff\xff" + head, sector = divmod(rest, sectors) + return bytes((head, ((cylinder >> 2) & 0xC0) | (sector + 1), cylinder & 0xFF)) + + +def mbr_bytes(parts, signature=None): + """A 512-byte MBR. parts is [(type, start_lba, sector_count, boot)]; boot is a bool.""" + if len(parts) > 4: + raise UsbError("an MBR holds four primary partitions") + if signature is None: + signature = struct.unpack(" 0: + os.pwrite(fd, zero, tail) + os.pwrite(fd, mbr_bytes(parts), 0) + os.fsync(fd) + say(f"OK erased {device} and wrote a new partition table") + except OSError as error: + raise UsbError(f"writing to {device} failed: {error.strerror}") from None + finally: + try: + import fcntl # noqa: PLC0415 - only needed here + fcntl.ioctl(fd, 0x125F) # BLKRRPART: ask the kernel to read the table just written + except OSError: + pass + os.close(fd) + + +def _mkfs(device, label=LABEL, fat=True): + if fat: + tool = shutil.which("mkfs.vfat") or shutil.which("mkfs.fat") + if not tool: + raise UsbError("mkfs.vfat is missing. Install dosfstools and try again.") + _run([tool, "-F", "32", "-n", label, device], timeout=300) + else: + tool = shutil.which("mkfs.exfat") + if not tool: + raise UsbError("mkfs.exfat is missing. Install exfatprogs (or exfat-utils) to use the full installer option.") + _run([tool, "-n", label, device], timeout=300) + + +def _mount(device, mountpoint): + os.makedirs(mountpoint, exist_ok=True) + _run(["mount", device, mountpoint], timeout=60) + return mountpoint + + +def _unmount_path(path): + # The payload is verified before this runs. umount waits for the kernel to write it out, and a slow stick can + # take minutes for 1.5 GB: a verified Sequoia stick was reported failed because the old 90-second limit ran out + # while the kernel was still flushing it. Flush the filesystem first, then give umount room for slow media. + _run(["sync", "-f", path], check=False, timeout=600) + p = _run(["umount", path], check=False, timeout=300) + if p.returncode != 0: + p = _run(["umount", "-l", path], check=False, timeout=60) + if p.returncode != 0: + raise UsbError(f"cannot unmount {path}; close programs using the stick and try again") + + +def write(disk, efi_build_dir, recovery_info, allow_large=False, progress=None, machine_profile=None, + erase_os=False, opt_in=None, full_pkg=None, extras=()): + """Erases the stick, then writes the recovery image and the EFI. Returns the payload result.""" + from . import fullinstaller, usbwriter, validate # noqa: PLC0415 + + ok, why = eligible(disk, allow_large) + if not ok: + raise UsbError("refusing: " + "; ".join(why)) + checked = validate.validate(efi_build_dir) + if not checked.get("ok"): + reasons = checked.get("invariants") or [checked.get("error") or "The OpenCore configuration did not pass validation."] + raise UsbError("The EFI must be rebuilt before erasing the stick: " + "; ".join(reasons) + + usbwriter.gone_hint(reasons)) + if machine_profile is not None: + from . import machine_handoff # noqa: PLC0415 + if machine_handoff.verified(efi_build_dir) != machine_profile: + raise UsbError("The machine profile changed before erasing the stick. Rebuild the EFI.") + found = find_same(list_disks(), disk.get("UniqueId"), disk.get("Size"), disk.get("FriendlyName"), disk.get("Path")) + if found is None: + raise UsbError("1401-DISK-RENUMBERED: the stick is not attached any more, or another disk has taken its " + "place. Nothing was erased. Press Refresh, pick the stick again and write.") + ok, why = eligible(found, allow_large) + if not ok: + raise UsbError("refusing: " + "; ".join(why)) + disk = found + if not erase_os: + held = os_partitions(disk) + if held: + raise UsbError(f"1401-OS-PARTITIONS: {stick_name(disk)} holds {', '.join(held)}. Nothing was erased.") + if full_pkg: + try: + fullinstaller.check_stick(int(disk.get("Size") or 0)) + fullinstaller.verify_xar(full_pkg) + except (fullinstaller.FullInstallerError, OSError) as error: + raise UsbError(f"1401-FULL-INSTALLER: {error}") from None + device = disk["Path"] + first = fullinstaller.FIRST_PARTITION if full_pkg else PART_CAP + parts = layout(int(disk["Size"]), first, second=bool(full_pkg)) + _unmount(disk) + _wipe(device, int(disk["Size"]), parts, say=lambda m: print(m, flush=True)) + first_device = partition_path(device, 1) + _settle(device, first_device) + _mkfs(first_device) + second_device = None + if full_pkg: + second_device = partition_path(device, 2) + _settle(device, second_device) + _mkfs(second_device, SECOND_LABEL, fat=False) + + work = tempfile.mkdtemp(prefix="1401-usb-") + mounted = [] + try: + root = _mount(first_device, os.path.join(work, "first")) + mounted.append(root) + result = usbwriter._write_payload(os.path.join(root, ""), efi_build_dir, recovery_info, progress, + machine_profile, usbwriter.stick_name(disk), opt_in) + for extra in extras: + folder = os.path.join(root, "NullMoth") + os.makedirs(folder, exist_ok=True) + shutil.copyfile(extra, os.path.join(folder, os.path.basename(extra))) + print(f"OK copied {os.path.basename(extra)} to the stick", flush=True) + if full_pkg: + _unmount_path(root) + mounted.remove(root) + second_root = _mount(second_device, os.path.join(work, "second")) + mounted.append(second_root) + print("STEP copying the full macOS installer to the second partition", flush=True) + try: + fullinstaller.place(os.path.join(second_root, ""), full_pkg, {"title": "macOS", "version": ""}, + progress=lambda done, total: print( + f"PROGRESS {int(done * 100 / total) if total else 0} copying the full macOS " + f"installer to the stick", flush=True)) + except (fullinstaller.FullInstallerError, OSError) as error: + raise UsbError(f"1401-FULL-INSTALLER: {error}. The first partition is a working online installer at " + f"{first_device}; only the full installer is missing.") from None + print(f"OK the full macOS installer is on the stick ({fullinstaller.LABEL})", flush=True) + result["root"] = first_device + print("STEP flushing the stick to flash; a slow USB stick can take a few minutes", flush=True) + return result + finally: + for path in reversed(mounted): + _unmount_path(path) + shutil.rmtree(work, ignore_errors=True) + + +def _owner_of(path): + try: + info = os.stat(path) + return info.st_uid, info.st_gid + except OSError: + return None + + +def _give_back(path, reference): + """The writer runs as root; a driver copied into the user's build folder should stay the user's.""" + owner = _owner_of(reference) + if owner and os.geteuid() == 0: + try: + os.chown(path, owner[0], owner[1]) + except OSError: + pass + + +def _stage_driver(efi, driver): + from . import usbwriter # noqa: PLC0415 + if not driver or not usbwriter.needs_nullmoth(efi): + return + package = usbwriter._pinned_package(driver) + cache = os.path.join(efi, ".cache") + os.makedirs(cache, exist_ok=True) + target = os.path.join(cache, os.path.basename(package)) + shutil.copyfile(package, target) + _give_back(target, efi) + + +def _recovery(efi, darwin, recovery_dir): + from . import apple, netsupport # noqa: PLC0415 + if netsupport.needs_local_image(efi): + print("NOTE " + netsupport.OFFLINE_INSTALLER_MESSAGE, flush=True) + info = apple.local_image(recovery_dir) if recovery_dir else None + if info: + print(f"OK using {info['name']} from {recovery_dir} (checked against Apple's signed chunklist while copying)", + flush=True) + return info + print("STEP asking Apple for the macOS recovery image", flush=True) + try: + info = apple.image_info(darwin) + except apple.AppleError as error: + if "403" in str(error): + raise UsbError("Apple's recovery server refused this network (HTTP 403). Connect through a VPN or another " + f"network and try again, or put BaseSystem.dmg and BaseSystem.chunklist into {recovery_dir} " + "and try again.") from None + raise + print(f"OK {info['name']} ({info['product']})", flush=True) + print("STEP checking that Apple will serve the download (nothing is erased yet)", flush=True) + try: + ready = apple.preflight(info) + except apple.AppleError as error: + raise UsbError(f"1401-APPLE-REFUSED: {error}. Your USB stick was not touched.") from None + print(f"OK Apple is serving {info['name']} ({ready['bytes'] / GiB:.2f} GB in {ready['chunks']} parts, " + f"signed chunklist verified)", flush=True) + return info + + +def cli_write(argv): + """write [--profile Report.json] [--driver tar.gz] [--extra file]... + [--recovery-dir dir] [--full-installer InstallAssistant.pkg] [--allow-large] [--erase-os-partitions] + [--stick-id id] [--stick-size bytes] [--stick-name name] [--arm-apps] + """ + from . import legacy, machine_handoff, usbwriter # noqa: PLC0415 + if len(argv) < 3: + raise UsbError("write needs a device, an EFI build directory and the Darwin major version") + device, efi, darwin = argv[0], argv[1], int(argv[2]) + older = legacy.read_marker(efi) + if older and older != darwin: + print(f"STOP this EFI was built for {legacy.NAME[older]}; build again for the macOS you want to write, or write " + f"{legacy.NAME[older]}. Nothing was erased.", flush=True) + return 2 + + def opt(name): + return [argv[i + 1] for i, value in enumerate(argv) if value == name and i + 1 < len(argv)] + + disks = list_disks() + disk = next((d for d in disks if d["Path"] == device), None) + ident = ((opt("--stick-id") or [""])[0], (opt("--stick-size") or [""])[0], (opt("--stick-name") or [""])[0]) + if any(ident): + size = int(ident[1]) if ident[1].isdigit() else 0 + found = find_same(disks, ident[0], size, ident[2], device) + if found is not None: + if found["Path"] != device: + print(f"OK the stick is {found['Path']} now (it was {device} when it was picked)", flush=True) + disk = found + if not disks: + print("STOP 1401-DISK-LIST-EMPTY: lsblk listed no disks. Nothing was erased.", flush=True) + return 1 + if disk is None: + print(f"STOP 1401-DISK-RENUMBERED: {device} is not attached any more. Nothing was erased. " + "Press Refresh, pick the stick again and write.", flush=True) + return 1 + ok, why = eligible(disk, "--allow-large" in argv) + if not ok: + print("STOP " + "; ".join(why), flush=True) + return 1 + profiles = opt("--profile") + if len(profiles) > 1: + raise UsbError("Select one current scan before writing the installer.") + handoff = machine_handoff.verified(efi, profiles[0] if profiles else None) + prepare_driver(efi) + _stage_driver(efi, (opt("--driver") or [""])[0]) + recovery_dir = (opt("--recovery-dir") or [RECOVERY_DIR])[0] + info = _recovery(efi, darwin, recovery_dir) + full_pkg = (opt("--full-installer") or [""])[0] or None + + last = [-1] + + def progress(done, total, *_): + percent = int(done * 100 / total) if total else 0 + if percent != last[0]: + last[0] = percent + print(f"PROGRESS {percent} downloading macOS recovery from Apple", flush=True) + + print(f"STEP erasing and writing {disk['Path']} ({usbwriter.stick_name(disk)})", flush=True) + opt_in = machine_handoff.opt_in(arm_apps="--arm-apps" in argv) + result = write(disk, efi, info, allow_large="--allow-large" in argv, progress=progress, machine_profile=handoff, + erase_os="--erase-os-partitions" in argv, opt_in=opt_in, full_pkg=full_pkg, extras=opt("--extra")) + print("OK verified build profile written to the stick (live identity remains unverified)", flush=True) + if opt_in: + print("OK ARM apps requested: after macOS starts, the 1401 Mac app offers to finish setting them up, if this " + "Mac can run them", flush=True) + print(f"OK the stick is ready at {result['root']}" + (" (NVIDIA driver included)" if result.get("nullmoth") else ""), + flush=True) + return 0 + + +def main(argv=None): + argv = list(sys.argv[1:] if argv is None else argv) + if not argv or argv[0] in ("list", "disks"): + try: + print(json.dumps(list_disks(), indent=2)) + return 0 + except UsbError as error: + print(f"STOP {error}", file=sys.stderr) + return 1 + if argv[0] == "write": + try: + return cli_write(argv[1:]) + except (UsbError, OSError, RuntimeError) as error: + print(f"STOP {type(error).__name__}: {error}", flush=True) + return 1 + if argv[0] == "prepare-driver": + try: + prepare_driver(argv[1] if len(argv) > 1 else "") + return 0 + except (UsbError, OSError, RuntimeError) as error: + print(f"STOP {type(error).__name__}: {error}", flush=True) + return 1 + print("usage: python3 -m p1401.linuxusb [list | write [options]]", + file=sys.stderr) + return 2 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/p1401/report.py b/p1401/report.py index f472e3f7..d1fe5fd7 100644 --- a/p1401/report.py +++ b/p1401/report.py @@ -113,6 +113,12 @@ def select(props, allowed): return result +# Linux names a monitor's connector after its DRM port ("card0-HDMI-A-1" is reported as "HDMI-A"); the builder's schema +# and its display checks use the Windows names. eDP and LVDS are the built-in panel, which Windows reports as Internal. +_CONNECTOR_NAMES = {"VGA": "VGA", "DVI": "DVI", "HDMI": "HDMI", "DP": "DP", "EDP": "Internal", "LVDS": "Internal"} +_ACPI_SB = re.compile(r"^[\\]?_SB(\.[A-Z0-9_]+)+$") + + def normalize(report): """Mutates and returns (report, notes). Each note names what was dropped and why.""" notes = [] @@ -143,6 +149,30 @@ def normalize(report): notes.append(f"BIOS: firmware type read as {ft!r} (extra text from PowerShell) - taken as {word}") _clean_text(report, notes) _field_gaps(report, notes) + # Linux scan: DRM port names ("HDMI-A", "eDP") and root-scope ACPI paths ("\HPET", "\AOD_") are not what the + # builder's schema and display checks know. It drops the whole report over one unknown value. A connector name still + # says which kind of port it is, so translate it. A path outside _SB cannot be reached by the SSDTs the engine + # writes, so leave just that path out; the device keeps its ID and still gets the matching quirks. + monitors = report.get("Monitor") + if isinstance(monitors, dict): + for name, props in monitors.items(): + if not isinstance(props, dict): + continue + was = props.get("Connector Type") + kind = str(was or "").upper().split("-")[0] + props["Connector Type"] = _CONNECTOR_NAMES.get(kind, "Uninitialized") + if props["Connector Type"] != was: + notes.append(f"Monitor: {name!r} connector type {was!r} - read as {props['Connector Type']} (Linux names " + "the port; the builder uses the Windows names)") + for section, devices in report.items(): + if section in ("CPU", "Motherboard", "BIOS") or not isinstance(devices, dict): + continue + for name, props in devices.items(): + path = props.get("ACPI Path") if isinstance(props, dict) else None + if path is not None and not _ACPI_SB.match(str(path)): + del props["ACPI Path"] + notes.append(f"{section}: {name!r} ACPI path {path!r} is outside _SB - left out (the builder only maps " + "devices under _SB; the device ID is still used)") if isinstance(report.get('GPU'), dict) and not report['GPU']: raise RuntimeError('The scan lists no graphics adapter at all, so there is nothing to plan a display for. Run Check this PC again; ' 'if it still lists none, send the log from the failed run.') diff --git a/p1401/scan.py b/p1401/scan.py index 0a4cad2f..5122d05e 100644 --- a/p1401/scan.py +++ b/p1401/scan.py @@ -1,5 +1,6 @@ """Scans this machine with Hardware Sniffer (upstream/Hardware-Sniffer, BSD-3, pinned in upstream/PINNED.json) and -writes Report.json + ACPI/*.aml, the two inputs engine.build needs. Windows (WMI) or Linux (sysfs, root for ACPI). +writes Report.json + ACPI/*.aml, the two inputs engine.build needs. Windows (WMI) or Linux (sysfs; the ACPI tables +are root-only, so Linux asks policykit once to copy them). Nothing gets sent anywhere. The Sniffer reads WMI/sysfs and its own bundled pci.ids/usb.ids. The one thing it downloads, acpidump.exe from GitHub (unverified), is replaced with a copy pinned by sha256 below. @@ -277,8 +278,14 @@ def _storage_drives_section(rows): def collect_storage_drives(): - """Windows only: the installed drives and their models, via PowerShell Get-Disk (FriendlyName is the model, BusType - tells USB from internal). Fail-safe: any error returns no rows, so the scan is never held up by this extra read.""" + """The installed drives and their models: PowerShell Get-Disk on Windows, lsblk on Linux. Fail-safe: any error + returns no rows, so the scan is never held up by this extra read.""" + if platform.system() == "Linux": + try: + from . import linuxusb # noqa: PLC0415 + return linuxusb.storage_rows() + except Exception: # noqa: BLE001 - an optional read; never block the scan + return [] if platform.system() != "Windows": return [] try: @@ -323,6 +330,10 @@ def _sniffer_body(out_dir, token): h.u.head = lambda *a, **k: None # it clears the console; a child has none if platform.system() == "Windows": h.check_acpidump = acpidump_path # pinned copy, not its own download + else: + # Its Linux dump calls `sudo cp`, which asks through a terminal this child does not have. linuxroot copies + # the tables after the report is written, through one policykit prompt. + h.dump_acpi_tables = lambda: None original_progress = h.hardware_info.utils.progress_bar def checkpoint_progress(*args, **kwargs): scan_evidence.save_partial(out_dir, token, getattr(h.hardware_info, "result", {})) @@ -335,7 +346,15 @@ def checkpoint_progress(*args, **kwargs): scan_evidence.save_partial(out_dir, token, getattr(h.hardware_info, "result", {})) h.export_hardware_report() _add_storage_drives(out_dir) # record drive models so a "no disk" report can name the exact SSD - h.dump_acpi_tables() + if platform.system() == "Linux": + from . import linuxroot # noqa: PLC0415 + try: + linuxroot.elevate_acpi(os.path.join(out_dir, "ACPI")) + except linuxroot.RootError as error: + print(str(error), file=sys.stderr) + return 1 + else: + h.dump_acpi_tables() acpi = os.path.join(out_dir, "ACPI") if platform.system() == "Windows": for note in windows_tables(acpi): # anything acpidump missed (FACP, MCFG, ...), straight from Windows diff --git a/tests/test_linux_report.py b/tests/test_linux_report.py new file mode 100644 index 00000000..16fb3561 --- /dev/null +++ b/tests/test_linux_report.py @@ -0,0 +1,66 @@ +"""A Linux scan names a monitor after its DRM port ("HDMI-A", "eDP") and can list ACPI paths from the root scope +("\\HPET"). The builder's report schema knows only the Windows connector names and _SB paths, and refuses the whole +report over one unknown value, so normalize translates the port and leaves out the unusable path.""" +import unittest + +from p1401 import report + + +def scan(**sections): + base = {"GPU": {"Card": {"Manufacturer": "NVIDIA", "Device ID": "10DE-1234"}}, + "Motherboard": {"Platform": "Desktop"}, "Input": {}, "Network": {}, + "USB Controllers": {}, "Storage Controllers": {}} + base.update(sections) + return base + + +class ConnectorNames(unittest.TestCase): + def test_drm_port_names_become_windows_ones(self): + for was, name in (("HDMI-A", "HDMI"), ("DP", "DP"), ("DVI-I", "DVI"), ("VGA", "VGA"), + ("eDP", "Internal"), ("LVDS", "Internal")): + out, notes = report.normalize(scan(Monitor={"Display": {"Connector Type": was, "Resolution": "1920x1080"}})) + self.assertEqual(out["Monitor"]["Display"]["Connector Type"], name, was) + if was == name: + self.assertEqual(notes, [], was) + else: + self.assertEqual(len(notes), 1, was) + self.assertIn("Linux names the port", notes[0]) + + def test_a_port_the_builder_does_not_know_is_uninitialized(self): + out, notes = report.normalize(scan(Monitor={"Display": {"Connector Type": "Virtual", "Resolution": "1024x768"}})) + self.assertEqual(out["Monitor"]["Display"]["Connector Type"], "Uninitialized") + self.assertEqual(len(notes), 1) + + def test_a_missing_connector_type_is_uninitialized(self): + out, notes = report.normalize(scan(Monitor={"Display": {"Resolution": "1024x768"}})) + self.assertEqual(out["Monitor"]["Display"]["Connector Type"], "Uninitialized") + self.assertIn("None", notes[0]) + + def test_windows_names_are_left_alone(self): + out, notes = report.normalize(scan(Monitor={"Display": {"Connector Type": "HDMI", "Resolution": "1920x1080"}})) + self.assertEqual(out["Monitor"]["Display"]["Connector Type"], "HDMI") + self.assertEqual(notes, []) + + +class AcpiPaths(unittest.TestCase): + def test_a_root_scope_path_is_left_out_and_sb_paths_are_kept(self): + out, notes = report.normalize(scan(**{"System Devices": { + "PNP0103": {"Bus Type": "ACPI", "Device": "PNP0103", "ACPI Path": "\\HPET"}, + "RTC": {"Bus Type": "ACPI", "Device": "PNP0B00", "ACPI Path": "\\_SB.PCI0.SBRG.RTC0"}}})) + self.assertNotIn("ACPI Path", out["System Devices"]["PNP0103"]) + self.assertEqual(out["System Devices"]["PNP0103"]["Device"], "PNP0103") + self.assertEqual(out["System Devices"]["RTC"]["ACPI Path"], "\\_SB.PCI0.SBRG.RTC0") + self.assertEqual(len(notes), 1) + self.assertIn("outside _SB", notes[0]) + + def test_the_path_is_left_out_in_any_device_section(self): + out, notes = report.normalize(scan(Sound={"Codec": {"Bus Type": "HDAUDIO", "Device ID": "10EC-0897", + "ACPI Path": "\\AOD_"}})) + self.assertNotIn("ACPI Path", out["Sound"]["Codec"]) + self.assertEqual(out["Sound"]["Codec"]["Device ID"], "10EC-0897") + self.assertEqual(len(notes), 1) + self.assertIn("outside _SB", notes[0]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_linux_root.py b/tests/test_linux_root.py new file mode 100644 index 00000000..dbbfe33c --- /dev/null +++ b/tests/test_linux_root.py @@ -0,0 +1,117 @@ +"""The Linux scan reads the firmware tables through pkexec and hands them to the builder under the names it expects +(`DSDT.aml`, not the `DSDT` sysfs uses). A root-only read that silently produced an empty ACPI folder would build a +Mac setup without the machine's own tables, so the copy checks the DSDT before saying it worked.""" +import os +import tempfile +import unittest +from unittest import mock + +from p1401 import linuxroot + + +def table_tree(root): + os.makedirs(os.path.join(root, "dynamic")) + files = {"DSDT": b"DSDT" + b"\0" * 60, "SSDT1": b"SSDT" + b"\0" * 60, + "dynamic/SSDT2": b"SSDT" + b"\1" * 60, "FACP": b"FACP" + b"\2" * 60} + for name, data in files.items(): + path = os.path.join(root, *name.split("/")) + with open(path, "wb") as fh: + fh.write(data) + return files + + +class CopyTables(unittest.TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.source = os.path.join(self.temp.name, "sysfs") + self.dest = os.path.join(self.temp.name, "ACPI") + self.files = table_tree(self.source) + os.makedirs(self.dest) + + def test_every_table_is_written_with_an_aml_suffix(self): + written = linuxroot.copy_tables(self.source, self.dest) + self.assertEqual(sorted(os.path.basename(p) for p in written), + ["DSDT.aml", "FACP.aml", "SSDT1.aml", "SSDT2.aml"]) + self.assertTrue(os.path.isfile(os.path.join(self.dest, "DYNAMIC", "SSDT2.aml"))) + with open(os.path.join(self.dest, "DSDT.aml"), "rb") as fh: + self.assertEqual(fh.read(), self.files["DSDT"]) + + def test_the_copied_tables_are_readable_by_the_user_who_runs_the_scan(self): + written = linuxroot.copy_tables(self.source, self.dest) + for path in written: + self.assertEqual(os.stat(path).st_mode & 0o777, 0o644) + + def test_a_directory_without_a_dsdt_is_a_failed_read_not_an_empty_result(self): + os.remove(os.path.join(self.source, "DSDT")) + with self.assertRaises(linuxroot.RootError) as cm: + linuxroot.copy_tables(self.source, self.dest) + self.assertIn("no DSDT", str(cm.exception)) + + def test_a_dsdt_that_is_not_a_dsdt_is_refused(self): + with open(os.path.join(self.source, "DSDT"), "wb") as fh: + fh.write(b"XXXX" + b"\0" * 32) + with self.assertRaises(linuxroot.RootError): + linuxroot.copy_tables(self.source, self.dest) + + def test_a_missing_sysfs_directory_is_a_failed_read(self): + with self.assertRaises(linuxroot.RootError): + linuxroot.copy_tables(os.path.join(self.temp.name, "absent"), self.dest) + with self.assertRaises(linuxroot.RootError): + linuxroot.copy_tables(self.source, None) + + def test_a_symlink_in_the_table_directory_is_not_followed(self): + os.symlink(os.path.join(self.source, "DSDT"), os.path.join(self.source, "DSDT2")) + written = linuxroot.copy_tables(self.source, self.dest) + self.assertNotIn(os.path.join(self.dest, "DSDT2.aml"), written) + + +class Names(unittest.TestCase): + def test_sysfs_names_become_the_builders_names(self): + self.assertEqual(linuxroot._destination("DSDT"), "DSDT.aml") + self.assertEqual(linuxroot._destination("dynamic/SSDT1"), "DYNAMIC/SSDT1.aml") + + def test_the_owner_argument_is_uid_colon_gid(self): + self.assertEqual(linuxroot._owner("1000:1000"), (1000, 1000)) + self.assertIsNone(linuxroot._owner(None)) + with self.assertRaises(linuxroot.RootError): + linuxroot._owner("1000") + + def test_table_has_checks_the_signature(self): + temp = tempfile.NamedTemporaryFile(delete=False) + self.addCleanup(os.remove, temp.name) + temp.write(b"DSDT" + b"\0" * 8) + temp.close() + self.assertTrue(linuxroot.table_has(temp.name, b"DSDT")) + self.assertFalse(linuxroot.table_has(temp.name, b"SSDT")) + self.assertFalse(linuxroot.table_has(temp.name + ".missing", b"DSDT")) + + +class Elevation(unittest.TestCase): + def test_when_already_root_the_copy_does_not_start_pkexec(self): + with mock.patch.object(linuxroot.os, "geteuid", return_value=0), \ + mock.patch.object(linuxroot, "_write_acpi") as direct, \ + mock.patch.object(linuxroot.subprocess, "run") as run: + self.assertIsNone(linuxroot.elevate_acpi("/tmp/acpi")) + direct.assert_called_once_with("/tmp/acpi", None) + run.assert_not_called() + + def test_a_dismissed_password_prompt_says_what_to_do(self): + failed = mock.Mock(returncode=126, stdout="", stderr="Request dismissed") + with mock.patch.object(linuxroot.os, "geteuid", return_value=1000), \ + mock.patch.object(linuxroot.shutil, "which", return_value="/usr/bin/pkexec"), \ + mock.patch.object(linuxroot.subprocess, "run", return_value=failed): + with self.assertRaises(linuxroot.RootError) as cm: + linuxroot.elevate_acpi("/tmp/acpi") + self.assertIn("Approve the password prompt", str(cm.exception)) + + def test_without_pkexec_the_error_names_the_package(self): + with mock.patch.object(linuxroot.os, "geteuid", return_value=1000), \ + mock.patch.object(linuxroot.shutil, "which", return_value=None): + with self.assertRaises(linuxroot.RootError) as cm: + linuxroot.elevate_acpi("/tmp/acpi") + self.assertIn("policykit", str(cm.exception)) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_linux_usb.py b/tests/test_linux_usb.py new file mode 100644 index 00000000..b4d3efa7 --- /dev/null +++ b/tests/test_linux_usb.py @@ -0,0 +1,289 @@ +"""The Linux stick writer decides which disk may be erased and builds the partition table itself, so the parts that can +be checked without a stick are checked here: lsblk parsing, eligibility, the MBR bytes and the layout around them.""" +import os +import struct +import tempfile +import unittest +from unittest import mock + +from p1401 import linuxusb + +GiB = linuxusb.GiB + + +def node(children=(), name="sdb", size=32 * GiB, tran="usb", ro=False, rm=True, serial="0123456789", + vendor="Kingston", model="DataTraveler 3.0", rota=False): + return {"name": name, "path": "/dev/" + name, "type": "disk", "size": size, "ro": ro, "rm": rm, "tran": tran, + "model": model, "vendor": vendor, "serial": serial, "rota": rota, "children": list(children)} + + +def part_node(name="sdb1", size=16 * GiB, fstype="vfat", parttype="0x0c", label="1401", mounts=()): + return {"name": name, "path": "/dev/" + name, "type": "part", "size": size, "fstype": fstype, + "parttype": parttype, "label": label, "mountpoints": list(mounts)} + + +def part(size=16 * GiB, fstype="vfat", parttype="0x0c"): + """A partition the way _disk hands it to the rest of the writer.""" + return {"Path": "/dev/sdb1", "Size": size, "FSType": fstype, "PartType": parttype, "Label": "1401", + "Mountpoints": []} + + +def disk(**kw): + args = dict(node()) + args.update(kw) + with mock.patch.object(linuxusb, "_identity_links", lambda device: []): + return linuxusb._disk(args) + + +class PartitionTable(unittest.TestCase): + def test_the_first_entry_is_bootable_and_points_at_the_fat_partition(self): + sector = linuxusb.mbr_bytes([(linuxusb.FAT32_LBA, 2048, 4194304, True)], signature=0x1234ABCD) + self.assertEqual(len(sector), 512) + self.assertEqual(sector[440:444], struct.pack(" Date: Wed, 18 Nov 2026 15:40:23 +0300 Subject: [PATCH 2/2] Allow AI-assisted development on this fork. Replace the upstream no-AI AGENTS note with fork workflow rules and Cursor project guidance. Signed-off-by: Stevex <310088924+kik4311@users.noreply.github.com> Co-authored-by: Cursor --- .cursor/rules/1401-project.mdc | 34 ++++++++++++++++++++ .cursor/rules/linux-app.mdc | 19 ++++++++++++ .cursor/rules/p1401-engine.mdc | 15 +++++++++ AGENTS.md | 57 +++++++++++++++++++++++++++++++--- 4 files changed, 121 insertions(+), 4 deletions(-) create mode 100644 .cursor/rules/1401-project.mdc create mode 100644 .cursor/rules/linux-app.mdc create mode 100644 .cursor/rules/p1401-engine.mdc diff --git a/.cursor/rules/1401-project.mdc b/.cursor/rules/1401-project.mdc new file mode 100644 index 00000000..49ba291c --- /dev/null +++ b/.cursor/rules/1401-project.mdc @@ -0,0 +1,34 @@ +--- +description: Core 1401 fork conventions for AI-assisted development +alwaysApply: true +--- + +# 1401 (fork) — project rules + +AI coding is allowed in this checkout. Follow `AGENTS.md` and `DEVELOPING.md`. + +## Layout + +- Engine steps: `p1401/` (`scan`, `engine`/`nullmoth`, `guide`, `usbwriter`/`linuxusb`, `report`) +- Linux GTK window: `linux/1401.py` — same four steps as Windows, no second engine +- Do not edit `upstream/` (pinned copies) +- Docs for behavior: `docs/HOW-IT-WORKS.md`, Linux specifics: `linux/README.md` + +## Hard constraints + +- No Apple code/binaries/SDK-derived files in the repo +- Third-party adds: pin URL/size/SHA-256; update `NOTICE.md` and `p1401/licenses.json` +- No secrets or personal hardware dumps +- Fail loud — never pretend a failed step succeeded +- Stick writing erases disks; prefer fake `lsblk`/ACPI fixtures in tests + +## Git / gh + +- Default push remote: `fork` (`kik4311/1401`), not `origin` (`nullmoth/1401`) +- Use `gh` for PRs/issues/checks on the fork; do not PR upstream unless Lev asks +- Commit only when Lev asks; use `git commit -s` (DCO) +- Leave binary noise alone (e.g. accidental `macserial.exe` diffs) unless asked + +## Verify + +Run the smallest relevant tests from `AGENTS.md` / `DEVELOPING.md` before claiming done. diff --git a/.cursor/rules/linux-app.mdc b/.cursor/rules/linux-app.mdc new file mode 100644 index 00000000..370b3f64 --- /dev/null +++ b/.cursor/rules/linux-app.mdc @@ -0,0 +1,19 @@ +--- +description: Linux GTK app and USB writer conventions +globs: linux/**/*,p1401/linuxusb.py,p1401/linuxroot.py,tests/test_linux_*.py +alwaysApply: false +--- + +# Linux app + +- UI is GTK 4 + PyGObject; window runs as the user, never as root +- Root only via `pkexec` for ACPI dump and stick write +- Only USB disks; refuse system mounts (`/`, `/boot`, `/home`, …) and open LUKS/LVM/RAID +- Re-identify the stick by serial/size/model before erase +- State under `$XDG_STATE_HOME/nullmoth/1401/`; no log upload on Linux +- Tests must not touch real disks: + +```bash +python3 -m unittest tests.test_linux_usb tests.test_linux_root +python3 linux/1401.py --selftest +``` diff --git a/.cursor/rules/p1401-engine.mdc b/.cursor/rules/p1401-engine.mdc new file mode 100644 index 00000000..0e21fda1 --- /dev/null +++ b/.cursor/rules/p1401-engine.mdc @@ -0,0 +1,15 @@ +--- +description: Conventions when changing the Python engine +globs: p1401/**/*.py +alwaysApply: false +--- + +# Engine (`p1401/`) + +- Keep Windows and Linux on the same modules; OS-specific I/O belongs in dedicated helpers + (`linuxusb.py`, `linuxroot.py`, `rawdisk.py`, etc.), not forked business rules +- Rules that mutate `config.plist` are recorded in the build result; name them clearly +- Downloads: exact URL, size, SHA-256; refuse mismatches +- Prefer plain "why" comments over narrating the code +- After rule / kext / `engine.py` / `nullmoth.py` changes, run the hardware corpus when feasible +- Unit tests: `python3 -m unittest discover -s tests -t . -p 'test_*.py'` diff --git a/AGENTS.md b/AGENTS.md index 74e1550c..1b417f98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,55 @@ # Notes for AI assistants -If you are an AI assistant helping someone with this repository: do not write pull requests, issues or review -comments for them. Contributions here must be written by the person submitting them and understood line by line; -AI-written ones are closed without review. Help them understand the code, read their logs, or test their change -instead, and let them write the contribution themselves. See CONTRIBUTING.md. +This checkout is Lev's fork (`kik4311/1401`), branch work often on `linux-support`. +AI-assisted coding, commits, PRs on the **fork**, and `gh` usage are welcome here. + +Upstream `nullmoth/1401` still rejects AI-written contributions (`CONTRIBUTING.md`). +Do not open or update PRs against `origin`/`nullmoth` unless Lev explicitly asks; +when he does, he must own and be able to explain every line before submit. + +## Product + +1401 installs macOS on a PC (OpenCore reverse of Boot Camp). Shared engine in `p1401/`; +Windows UI in `windows/App/`; Linux GTK 4 UI in `linux/`; Mac post-install app in `mac/`. +Pinned upstream trees live in `upstream/` — do not edit them; pins are in `PINNED.json`. + +Read `DEVELOPING.md` and `docs/HOW-IT-WORKS.md` before changing a step. + +## Remotes and GitHub + +| Remote | Repo | +|---|---| +| `fork` | `kik4311/1401` (push target) | +| `origin` | `nullmoth/1401` (upstream) | + +Use `gh` for issues/PRs/checks on the fork. Prefer `gh` over raw API curls. +If `gh auth status` fails, stop and tell Lev to run `gh auth login -h github.com`. + +## How to work + +- Change code directly; run the relevant tests before claiming done. +- One focused change per branch/PR on the fork. +- Sign off commits when Lev asks to commit (`git commit -s`) — DCO still applies. +- English in project files, docs, commit messages, and PR text unless Lev asks otherwise. +- Never commit secrets, real hardware dumps, or Apple binaries/SDK material. +- Fail loud: a step that cannot finish must stop with a clear reason. + +## Tests (minimum) + +```bash +python3 -m unittest discover -s tests -t . -p 'test_*.py' +``` + +Linux UI / writer: + +```bash +python3 -m unittest tests.test_linux_usb tests.test_linux_root +python3 linux/1401.py --selftest # needs a display +``` + +Corpus (rules / `engine.py` / `nullmoth.py`): + +```bash +python3 tests/corpus/fetch.py +python3 tests/run_corpus.py build +```