From f5d488dae7d4864631d92d11e538db486251d126 Mon Sep 17 00:00:00 2001 From: James Calligeros Date: Thu, 15 May 2025 08:06:47 +1000 Subject: [PATCH 1/2] alt: clear out This is in preparation for our new alt-distro policy, which will be gazetted by the next commit Signed-off-by: James Calligeros --- docs/alt/alt-distros.md | 25 ---- docs/alt/installing-gentoo.md | 132 --------------------- docs/alt/ubuntu-gambas.md | 51 --------- docs/alt/ubuntu-godot.md | 40 ------- docs/alt/ubuntu-qemu.md | 210 ---------------------------------- docs/sw/u-boot.md | 7 +- mkdocs.yml | 1 - 7 files changed, 3 insertions(+), 463 deletions(-) delete mode 100644 docs/alt/alt-distros.md delete mode 100644 docs/alt/installing-gentoo.md delete mode 100644 docs/alt/ubuntu-gambas.md delete mode 100644 docs/alt/ubuntu-godot.md delete mode 100644 docs/alt/ubuntu-qemu.md diff --git a/docs/alt/alt-distros.md b/docs/alt/alt-distros.md deleted file mode 100644 index 6f5cb6e9..00000000 --- a/docs/alt/alt-distros.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Alternative Distributions -summary: - Linux distros and other OSes that have added support for - the Apple Silicon platform ---- - -The primary supported distribution is the [Fedora Asahi Remix](https://asahilinux.org/fedora/), but several members of the community have contributed guides and pre-built artifacts in order to use other distros on Apple Silicon Macs. These efforts are listed here. Please remember that these are user-contributed, and the Asahi Linux project cannot provide support or any guarantee of compatibility, functionality, or safety. - -| Distro | Maintainer | Installation Guide | -|--------|------------|--------------------| -| Alpine Linux | IRC: mps () | | -| AOSC OS | | | -| Arch Linux ARM | | | -| CentOS Stream | | | -| Debian | | | -| deepin | | | -| deepin | deepin M1 SIG | | -| Fedora | | | -| Gentoo
(LiveCD method) | IRC: chadmed () | [Installing Gentoo with LiveCD](installing-gentoo.md) | -| NixOS | IRC: tpw_rules () | | -| NixOS (Asahi-Installer package) | | | -| Rocky Linux | | | -| Ubuntu | | | -| Void Linux | | | diff --git a/docs/alt/installing-gentoo.md b/docs/alt/installing-gentoo.md deleted file mode 100644 index 76faf5d3..00000000 --- a/docs/alt/installing-gentoo.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Installing Gentoo ---- - -**This page contains distro-specific information. This documentation** -**repo is not for distro-specific documentation. The proper place for** -**this is the distro's own documentation system. This page will be removed** -**soon.** - -## Table of Contents -- [Introduction](#introduction) -- [Prerequisites](#important-prerequisite-information) -- [Installation](#step-1-set-up-the-asahi-u-boot-environment) - * [Step 1: Set up the Asahi U-Boot Environment](#step-1-set-up-the-asahi-u-boot-environment) - * [Step 2: Acquire the Gentoo Asahi LiveCD image](#step-2-acquire-the-gentoo-asahi-livecd-image) - * [Step 3: Boot into the LiveCD](#step-3-boot-into-the-livecd) - * [Step 4: Install Asahi support files](#step-4-install-asahi-support-files) - * [Step 5: Have fun!](#step-5-have-fun) -- [Maintenance](#maintenance) - * [Updating U-Boot and m1n1](#updating-u-boot-and-m1n1) - * [Upgrading the kernel](#upgrading-the-kernel) - * [Syncing the Asahi overlay](#syncing-the-asahi-overlay) - -## Introduction -Installing Gentoo on Apple Silicon is not that different to doing so on a bog-standard amd64 machine. -We have a LiveCD image that is almost identical to the standard Gentoo arm64 one, customised only to -enable it to boot on Apple Silicon devices. - -The only major deviation from the Handbook is using [chadmed's `asahi-gentoosupport`](https://github.com/chadmed/asahi-gentoosupport) package to automate the -installation of the kernel, GRUB, overlay, m1n1, and U-Boot. You are of course welcome to attempt installing -these manually, however it will take you longer than bootstrapping the rest of the system combined. - -This guide will assume that you are familiar withe the Asahi Linux installer and will not walk you through using -it. - -If you've never used a Portage overlay before, take a few minutes to read the final section on maintaining the system. -Failure to do so properly may result in you missing critical system updates or leaving your machine in an unbootable state. - -## Important prerequisite information -* Please do not use `genkernel` to build your initramfs. The only supported initramfs generator is `dracut`. The `asahi-configs` - package installed later will supply the necessary configuration files to make `dracut` work seamlessly. - -* U-Boot's USB stack is not fantastic, to say the least. You may find that various USB sticks or keyboards do not work reliably - with it. Unfortunately, there is nothing we can do about this at the moment and you will just have to try different USB - devices until you find one that works. - -## Step 1: Set up the Asahi U-Boot Environment -Use the Asahi Installer to set up the minimal m1n1 + U-boot UEFI environment. Ensure that you tell the installer to -leave the amount of free space you want for your Gentoo system. It may be easier to simply use the Fedora Asahi Remix -Minimal installation option. We won't be using it, but it will guarantee that space is reserved for your root filesystem. - -It is assumed going forward that you have fully "completed" the Asahi installation. - -## Step 2: Acquire the Gentoo Asahi LiveCD image -We build lightly customised Gentoo LiveCDs which allow booting on Apple Silicon machines. Grab the latest one from -https://chadmed.au/pub/gentoo/. - -The LiveCDs are built using the standard Gentoo release engineering tooling. The Catalyst specfiles can be found at -https://github.com/chadmed/gentoo-asahi-releng. - -Flash this on to a USB stick using your favourite method. As always, plain old `dd` works best. - -## Step 3: Boot into the LiveCD -Boot the machine with the USB stick you flashed plugged in. U-Boot will enumerate your USB devices, then give you 2 seconds -to interrupt its automatic boot sequence. If you opted for the m1n1 + U-Boot installation option, you should be safe -to just let it continue booting. It will automatically boot from your USB stick. - -If you installed one of the complete operating system images, you will need to interrupt the boot process and force -U-Boot to boot from the USB. Once you have interrupted U-Boot's automatic boot sequence, run this series of commands: - -``` -setenv boot_targets "usb" -setenv bootmeths "efi" -boot -``` - -If your U-Boot plays nicely with your USB stick, this will boot you into the LiveCD's GRUB. From here, you can simply -follow the Gentoo Handbook for amd64, stopping only when it is time to install a kernel. - -**NOTE**: When partitioning your machine, it is absolutely vital that you do _not_ alter _any_ partitions other than -the space reserved for your rootfs. This includes the EFI System Partition set up by the Asahi Installer. You are free -to partition the rootfs space in any manner you wish, but do not modify any other structure on the disk. You will most -likely require a DFU restore of your Mac if you do. - -## Step 4: Install Asahi support files -Merge Git by running `emerge -av dev-vcs/git`, then clone `chadmed/asahi-gentoosupport` from GitHub. Run `./install.sh` and follow the prompts. This will -* Install the Asahi Overlay, which provides the kernel, boot tooling and (possibly) patched packages -* Install the `sys-apps/asahi-meta` package, which will pull in all the Asahi-specific goodies necessary for booting, - including a dist-kernel. -* Install and update GRUB. - -This allows you to skip setting up GRUB, the kernel, and the boot tooling yourself which can be a bit of a hassle on these -machines and may leave you with an unbootable Linux setup. - -## Step 5: Have fun! -Finish off the rest of your usual Gentoo install procedure, reboot, and have fun! It's a good idea to customise the kernel as -you see fit since the running config will be based on Arch/Asahi Linux. Remember to save the running kernel and initramfs as -a fallback so you can easily boot it from GRUB should anything go wrong. - -## Maintenance -Getting and applying system updates is a little more involved than a totally vanilla Gentoo installation. You need to keep -the Asahi overlay synced and make sure that system firmware is updated correctly. - -### Updating U-Boot and m1n1 -When you update the U-Boot or m1n1 packages, Portage will only install the resultant binaries to `/usr/lib/asahi-boot/`. -This is both a security and a reliability measure. m1n1 ships with a script, `update-m1n1`, which must be run as root -every time you update the kernel, U-Boot, or m1n1 itself. This script is responsible for collecting the m1n1, U-Boot -and Devicetree blobs, packaging them up into a single binary object, and installing it on the EFI System Partition. -For more information on how this works and why it must work this way, consult [Open OS Ecosystem on Apple Silicon Macs](../platform/open-os-interop.md) - -### Upgrading the kernel -When you are running through a kernel upgrade, it is extremely important that you update the Stage 2 m1n1 payload at the -same time. m1n1 Stage 2 contains the Devicetree blobs required for the kernel to find the hardware, probe it properly, and -boot the system. Devicetrees are not stable, and a kernel upgrade with new DTs may result in an unbootable system, loss of -function, or missing out on a newly enabled feature. To make sure this does not occur, it is imperative that you run -```bash -root# update-m1n1 -``` -after *every* kernel upgrade. - -**Note for developers and advanced users:** You may also wish to install multiple kernels, and make use of `eselect kernel` -to swap the symlink to `/usr/src/linux`. This is supported, however you *must* run `eselect kernel set` and `update-m1n1` -before *every* reboot into different kernel. This is to ensure that you are always booting with the correct DTBs. - -### Syncing the Asahi overlay -In order to receive Asahi-specific updates, you must ensure that the Asahi overlay remains synchronised. Portage will -do this for you if you use `emerge --sync`, but *not* if you use `emerge-webrsync`. To synchronise the overlay manually, run -```bash -root# emaint -r asahi sync -``` -before trying to update. No other steps are necessary to make sure that packages are updated, just update -your system like you normally would at this point. diff --git a/docs/alt/ubuntu-gambas.md b/docs/alt/ubuntu-gambas.md deleted file mode 100644 index 2e5837bd..00000000 --- a/docs/alt/ubuntu-gambas.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Ubuntu Gambas ---- - -**This page contains distro-specific information. This documentation** -**repo is not for distro-specific documentation. The proper place for** -**this is the distro's own documentation system. This page will be removed** -**soon.** - -Tested on Ubuntu 22.10 Asahi on M1 Air. - -https://gambas.sourceforge.net - -Change to root during installing packages: -``` -sudo su - -apt-get update && apt-get install -y build-essential \ -g++ automake autoconf libbz2-dev libzstd-dev \ -default-libmysqlclient-dev unixodbc-dev libpq-dev \ -libsqlite0-dev libsqlite3-dev libglib2.0-dev \ -libgtk2.0-dev libcurl4-gnutls-dev libgtkglext1-dev \ -libpcre3-dev libsdl-sound1.2-dev libsdl-mixer1.2-dev \ -libsdl-image1.2-dev libxml2-dev libxslt1-dev \ -librsvg2-dev libpoppler-dev libpoppler-glib-dev \ -libpoppler-private-dev libpoppler-cpp-dev libasound2-dev \ -libdirectfb-dev libxtst-dev libffi-dev libqt4-dev \ -libqtwebkit-dev libqt4-opengl-dev libglew-dev \ -libimlib2-dev libv4l-dev libsdl-ttf2.0-dev \ -libgdk-pixbuf2.0-dev linux-libc-dev libgstreamer1.0-dev \ -libgstreamer-plugins-base1.0-dev libcairo2-dev \ -libgsl-dev libncurses5-dev libgmime-2.6-dev \ -libalure-dev libgmp-dev libgtk-3-dev libsdl2-dev \ -libsdl2-mixer-dev libsdl2-ttf-dev libsdl2-image-dev \ -sane-utils libdumb1-dev libqt5opengl5-dev \ -libqt5svg5-dev libqt5webkit5-dev libqt5x11extras5-dev \ -qtbase5-dev qtwebengine5-dev libwebkit2gtk-4.0-dev \ -git libssl-dev - -exit -``` -As normal user: -``` -./reconf-all - -./configure -C --disable-keyring - -make -j$(nproc) - -sudo make install -``` diff --git a/docs/alt/ubuntu-godot.md b/docs/alt/ubuntu-godot.md deleted file mode 100644 index 735b94fd..00000000 --- a/docs/alt/ubuntu-godot.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Ubuntu Godot ---- - -**This page contains distro-specific information. This documentation** -**repo is not for distro-specific documentation. The proper place for** -**this is the distro's own documentation system. This page will be removed** -**soon.** - -Tested on Ubuntu 22.10 Asahi on M1 Air. - -https://godotengine.org - -Building Godot 3.5, because currently 4.x seems to crash when starting. - -https://docs.godotengine.org/en/latest/development/compiling/compiling_for_linuxbsd.html - -``` -sudo apt -y install build-essential scons \ -pkg-config libx11-dev libxcursor-dev libxinerama-dev \ -libgl1-mesa-dev libglu-dev libasound2-dev \ -libpulse-dev libudev-dev libxi-dev libxrandr-dev - -git clone https://github.com/godotengine/godot.git - -git checkout remotes/origin/3.5 - -cd godot - -scons -j$(nproc) platform=linuxbsd - -cd bin - -./godot.x11.tools.64 -``` -If you don't have hardware acceleration version of Asahi, -you can use slower software GL: -``` -LIBGL_ALWAYS_SOFTWARE=1 ./godot.x11.tools.64 -``` diff --git a/docs/alt/ubuntu-qemu.md b/docs/alt/ubuntu-qemu.md deleted file mode 100644 index 593590cc..00000000 --- a/docs/alt/ubuntu-qemu.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Ubuntu Qemu ---- - -**This page contains distro-specific information. This documentation** -**repo is not for distro-specific documentation. The proper place for** -**this is the distro's own documentation system. This page will be removed** -**soon.** - -Tested on Ubuntu 22.10 Asahi on M1 Air. - -See [this page](alt-distros.md) for other Ubuntu Asahi install info. - -Also installs virt-manager. - -Slirp included when compiling, to have user networking: -https://bugs.launchpad.net/qemu/+bug/1917161 - -``` -sudo apt -y install git libglib2.0-dev libfdt-dev \ -libpixman-1-dev zlib1g-dev ninja-build \ -git-email libaio-dev libbluetooth-dev \ -libcapstone-dev libbrlapi-dev libbz2-dev \ -libcap-ng-dev libcurl4-gnutls-dev libgtk-3-dev \ -libibverbs-dev libjpeg8-dev libncurses5-dev \ -libnuma-dev librbd-dev librdmacm-dev \ -libsasl2-dev libsdl2-dev libseccomp-dev \ -libsnappy-dev libssh-dev \ -libvde-dev libvdeplug-dev libvte-2.91-dev \ -libxen-dev liblzo2-dev valgrind xfslibs-dev \ -libnfs-dev libiscsi-dev flex bison meson \ -qemu-utils virt-manager - -git clone https://gitlab.com/qemu-project/qemu.git - -cd qemu - -git submodule init - -git submodule update - -git clone https://gitlab.freedesktop.org/slirp/libslirp - -cd libslirp - -meson build - -ninja -C build install - -cd .. - -mkdir build - -cd build - -../configure --enable-slirp - -make -j$(nproc) - -sudo make install -``` - -## Networking examples for various OS - -https://wiki.qemu.org/Documentation/Networking - -## ReactOS x86 32bit with networking - -https://reactos.org - -``` -wget reactos-32bit-bootcd-nightly.7z - -7z x reactos-32bit-bootcd-nightly.7z - -mv reactos*.iso ReactOS.iso -``` -20G is max growable disk size here: -``` -qemu-img create -f qcow2 ReactOS.qcow2 20G -``` -Here `-m 3G` is 3 GB RAM. - -Edit `start.sh` and set it executeable `chmod +x start.sh` with this content: -``` -qemu-system-i386 -m 3G -drive if=ide,index=0,media=disk,file=ReactOS.qcow2 \ --drive if=ide,index=2,media=cdrom,file=ReactOS.iso -boot order=d \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` -Then run `./start.sh` - -## WinXP x86 32bit with networking - -1) Create growable harddisk image of 80 GB: -``` -qemu-img create -f qcow2 winxp.qcow2 80G -``` -2) Start install from winxp.iso - -Edit `start.sh` and set it executeable `chmod +x start.sh`, here `-m 4G` is 4 GB RAM: -``` -qemu-system-i386 -m 4G -drive if=ide,index=0,media=disk,file=winxp.qcow2 \ --drive if=ide,index=2,media=cdrom,file=winxp.iso -boot order=d \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` -3) After install, boot without iso -``` -qemu-system-i386 -m 4G -drive if=ide,index=0,media=disk,file=winxp.qcow2 \ --boot order=c \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` - -## Win10 x86_64 with networking - -1) Create growable harddisk image of 80 GB: -``` -qemu-img create -f qcow2 win10.qcow2 80G -``` -2) Start install from win10.iso - -Edit `start.sh` and set it executeable `chmod +x start.sh`, here `-m 4G` is 4 GB RAM: -``` -qemu-system-x86_64 -m 4G -drive if=ide,index=0,media=disk,file=win10.qcow2 \ --drive if=ide,index=2,media=cdrom,file=win10.iso -boot order=d \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` -3) After install, boot without iso -``` -qemu-system-x86_64 -m 4G -drive if=ide,index=0,media=disk,file=win10.qcow2 \ --boot order=c \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` - -## Win11 x86_64 with networking - -1) Create growable harddisk image of 80 GB: -``` -qemu-img create -f qcow2 win11.qcow2 80G -``` -2) Start install from win11.iso - -Edit `start.sh` and set it executeable `chmod +x start.sh`, here `-m 4G` is 4 GB RAM, `-usbdevice tablet` makes using mouse more exact: -``` -qemu-system-x86_64 -hda win11.qcow2 -cdrom win11.iso -boot d \ --smp 2 -m 4G -usbdevice tablet \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` - -3) When installing Win11 - -a) Use bypass registry keys: - -https://blogs.oracle.com/virtualization/post/install-microsoft-windows-11-on-virtualbox - -b) Figure out UEFI and TPM and how to activate it, not tested: - -- -- -- -- -- -- - -``` -sudo apt-get install dh-autoreconf libssl-dev \ - libtasn1-6-dev pkg-config libtpms-dev \ - net-tools iproute2 libjson-glib-dev \ - libgnutls28-dev expect gawk socat \ - libseccomp-dev make -y - -git clone https://github.com/stefanberger/swtpm - -cd swtpm - -./autogen.sh --with-openssl --prefix=/usr - -make -j4 - -make -j4 check - -sudo make install -``` - -3) After install, boot without iso -``` -qemu-system-x86_64 -hda win11.qcow2 -boot c \ --smp 2 -m 8G -usbdevice tablet \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` - -## Ubuntu x86_64 with networking - -1) Create growable harddisk image of 80 GB: -``` -qemu-img create -f qcow2 ubuntu.qcow2 80G -``` -2) Start install from ubuntu.iso - -Edit `start.sh` and set it executeable `chmod +x start.sh`, here `-m 4G` is 4 GB RAM: -``` -qemu-system-x86_64 -m 4G -drive if=ide,index=0,media=disk,file=ubuntu.qcow2 \ --drive if=ide,index=2,media=cdrom,file=ubuntu.iso -boot order=d \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` -3) After install, boot without iso -``` -qemu-system-x86_64 -m 4G -drive if=ide,index=0,media=disk,file=ubuntu.qcow2 \ --boot order=c \ --serial stdio -netdev user,id=n0 -device rtl8139,netdev=n0 -``` diff --git a/docs/sw/u-boot.md b/docs/sw/u-boot.md index 4a4bd091..f6c7e284 100644 --- a/docs/sw/u-boot.md +++ b/docs/sw/u-boot.md @@ -5,12 +5,11 @@ title: Das U-Boot U-Boot is the default payload for m1n1 stage 2, and is used to provide a standard preboot environment familiar to AArch64 developers. External boot is not supported with the native Apple Silicon boot tooling, making U-Boot a hard necessity for providing a PC-like boot environment. This page explains how we use U-Boot and how to manually build and -install it. It is assumed that you are working on an Apple Silicon machine using a well-supported distro, meaning either -Asahi itself or one listed at [Alternative Distros](../alt/alt-distros.md). +install it. It is assumed that you are working on an Apple Silicon machine using a well-supported distro. Do note that the process for building and installing U-Boot listed here is for documentation and development purposes only. If you are an Asahi user and not interested in hacking on U-Boot or m1n1, they are managed automatically -via `pacman`. The same should be true for all (most) distros listed at [Alternative Distros](../alt/alt-distros.md). +via `pacman`. ## Standard boot flow We make use of U-Boot's UEFI implementation to load and execute a UEFI binary located at `/EFI/BOOT/BOOTAA64.EFI` @@ -28,7 +27,7 @@ do things like boot off external media, execute arbitrary UEFI code, load and ju * USB hubs with integrated SD card readers will cause your machine to hard reset if the slot is empty. The fix for this is queued. ## Prerequisites -* An Apple Silicon machine running Asahi or a distro listed at [Alternative Distros](../alt/alt-distros.md) +* An Apple Silicon machine running Asahi * A clean build of m1n1, see the [m1n1 User Guide](m1n1-user-guide.md) * The Apple DTBs from `AsahiLinux/linux`. Compiling these is out of scope for this document. * The Asahi EFI System Partition mounted at `/boot/efi/`. diff --git a/mkdocs.yml b/mkdocs.yml index 62cd0c8f..16990713 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,7 +27,6 @@ nav: - For users: - Fedora Asahi Remix Documentation : https://docs.fedoraproject.org/en-US/fedora-asahi-remix/ - Broken Software: sw/broken-software.md - - Alternative Distros: alt/alt-distros.md - For developers: - Yaks in need of shaving (HELP WANTED!): project/help-wanted.md - Tethered Boot Setup (For Developers): sw/tethered-boot.md From b704002c7da6a4e57e3e82ff0f1d877149c5003e Mon Sep 17 00:00:00 2001 From: James Calligeros Date: Thu, 15 May 2025 08:16:49 +1000 Subject: [PATCH 2/2] alt: policy: add Add our new distribution guidelines Signed-off-by: James Calligeros --- docs/alt/policy.md | 192 +++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 + 2 files changed, 194 insertions(+) create mode 100644 docs/alt/policy.md diff --git a/docs/alt/policy.md b/docs/alt/policy.md new file mode 100644 index 00000000..1d992567 --- /dev/null +++ b/docs/alt/policy.md @@ -0,0 +1,192 @@ +--- +title: Asahi Linux Distribution Guidelines +--- + +Asahi Linux exists to reverse engineer, document, and ultimately +implement Linux support for the Apple Silicon platform. While +[Fedora Asahi Remix](https://fedora-asahi-remix.org) is our flagship distribution, representing the +state of the art of Linux support on Apple Silicon, we have always +encouraged interested parties representing other distributions +(and even other FLOSS operating systems like [OpenBSD](https://www.openbsd.org/)) to implement +support for the platform. + +Traditionally, it has been unclear whether or not these efforts +are officially endorsed by the Asahi Linux project. This has led +to frustration and confusion on the part of users, distro maintainers, +and Asahi developers alike. Some distros have been semi-integrated +into the project on account of being the distro of choice of +our developers, while others are listed as "supported" in our +documentation despite being drive-by attempts at support led +by a single person who has long since given up. + +To remedy this situation, we have compiled a set of guidelines +for distros looking to implement support for Apple Silicon. We +heavily encourage all distributions to strive toward them in the +interests of a consistently good experience for all Apple Silicon +users regardless of their distribution of choice. + +These criteria are entirely optional. Everyone is of course +welcome to experiment with and enjoy their favourite distribution +on the Apple Silicon platform, and we will always enable and +encourage this. These guidelines are aimed at mature/mainstream +distributions interested in supporting Apple Silicon in an +official or semi-official capacity. Distros which demonstrate +adherence to these guidelines will be eligible for listing in +our documentation as viable alternatives to Fedora Asahi Remix. + +## Required reading +Please familiarise yourself with the [Introduction to Apple Silicon](../platform/introduction.md), +[Open OS Platform Integration](../platform/open-os-interop.md), +and [Boot Process Guide](boot-process-guide.md) documents before continuing. + +## Official buy-in +Your project to implement Apple Silicon support in your distro of +choice must be directly supported - or otherwise acknowledged - by +your distro's official maintainers. This may vary depending on your +distro's policy and organisational structure, however typically this +will take the form of an official taskforce/group endorsed by the +distro, e.g. the [Fedora Asahi SIG](https://fedoraproject.org/wiki/SIGs/Asahi), +[Gentoo Asahi Project](https://wiki.gentoo.org/wiki/Project:Asahi), or Debian's +[Team Bananas](https://wiki.debian.org/Teams/Bananas). + +## Complete and up to date packages +You must have the following list of packages present in your distro. +Preferably, these will be in official package repositories. However, +it is acceptable for them to be in a third-party repository (e.g. +Fedora COPR, Portage Overlay) provided that your repository has been +endorsed by your distro's official maintainers. + +* [The Asahi Linux fork of the Linux kernel](https://github.com/AsahiLinux/linux) +* [m1n1](https://github.com/AsahiLinux/m1n1) +* [The Asahi Linux fork of Das U-Boot](https://github.com/AsahiLinux/u-boot) +* [asahi-scripts](https://github.com/AsahiLinux/asahi-scripts) or equivalent configuration presets/scripts +* [tiny-dfr](https://github.com/AsahiLinux/tiny-dfr) +* [asahi-firmware](https://github.com/AsahiLinux/asahi-installer) (including its dependency lzfse) +* [speakersafetyd](https://github.com/AsahiLinux/speakersafetyd) +* [asahi-audio](https://github.com/AsahiLinux/asahi-audio) (and its LV2 plugin dependencies) + +New versions of the above software must be packaged in your +distro's bleeding edge (e.g. Fedora Rawhide or Gentoo's +unstable package stream) within 2 weeks of becoming available upstream. + +## Installation procedure +Asahi Linux uses Das U-Boot's UEFI environment to chainload standard UEFI +bootloaders, such as GRUB and systemd-boot. The Asahi Installer is capable +of setting up a minial UEFI-only environment capable of booting UEFI +executables on removable media. This provides users an installation +experience that is almost identical to a standard amd64-based workstation. +Building Apple Silicon support into your distro's existing AArch64 bootable +media (e.g. via a secondary Asahi kernel selectable at the UEFI bootloader) +allows the reuse of all your distro's existing upstream AArch64 resources, +and negates the need to fork the Asahi Installer. + +When selecting the minimal UEFI environment installation option, the Asahi +Installer can be directed to create free space for a future root filesystem. +Your guide must instruct users to use this facility to prepare their disk +for your distribution rather than attempting to manually shrink or alter +APFS containers via your installer. + +Your installation process should be as close to your distro's standard +installation procedure as possible. If your distro has an officially endorsed +automatic installer (e.g. Anaconda), then it must be used. If your +distro follows a manual guided installation (e.g. Gentoo Handbook), then +you must have a clear and easy to follow guide specific to Apple Silicon. +You must not instruct your users to materially deviate from your distro's +prescribed official installation procedure. + +If your installer attempts to partition the user's disk automatically, then +you _should_ explicitly warn your users against making use of it if it cannot +be made to ignore APFS containers. Altering or destroying any of the +on-disk APFS containers will require your users to DFU restore their Mac. + +Instead, your installation procedure _must_ encourage manual partitioning, +with a section in your guide explaining the dangers of carelessly altering +the partition table. Users must be made aware that it is _never_ safe to +alter or rearrange _any_ disk structure other than the free space left by +the Asahi Installer. + +_Note: We are actively working on improving the safety of common disk partitioning +and installation tooling. We may tighten these requirements in the future as +tools such as cfdisk, blivet, Anaconda, etc. become capable of automatically +handling Apple Silicon devices safely._ + +Your installation must install the Asahi-specific packages listed above as +part of the installation procedure, or a subset suitable for the installation +type. For example, server operating systems may choose to forego automatically +installing the audio enablement packages. + +## Infrastructure and hosting +You or your distro will assume all responsibility for any required hosting +or infrastructure other than the Asahi Installer. This includes any +documentation, packages, CI runners to build packages, CDNs etc. The Asahi +Linux project cannot do this for you. + +## Support +Your distro must have first-class, mature support for AArch64/ARM64 upstream. + +You or your distro will provide official support for distro-specific issues +relating to the Apple Silicon platform. This includes acting as the first +point of contact for users when they encounter bugs or other issues with any +packaged software. Apple Silicon should be a first-class platform within your +distro's broader AArch64/ARM64 support. + +## Using a forked installer and disk image +There are two supported mechanisms for installing Linux on Apple Silicon Macs. +As an alternative to the standard UEFI media method described above, the Asahi +Installer can free space on the NVMe drive and then flash a prebuilt OS image +into that space. This mimics other AArch64 embedded platforms, such as the +Raspberry Pi, and provides a way for users not familiar or confident with +installing Linux an easy way to get started at the expense of customisability. +For more details on how this works, please see [AsahiLinux/asahi-installer](https://github.com/AsahiLinux/asahi-installer). + +We expect distros to fork, modify, and host the reference Asahi Installer themselves +if choosing to go down this route. We cannot host your images or make distro-specific +changes to our reference installer. + +Your disk image based installation should follow these guidelines: + +* The installer and disk images are built and hosted by the distro officially +* The disk images are ZIPped and streamable from the Web +* The OS scrambles the root partition's UUID on first boot +* The OS grows its root partition into trailing free space on first boot +* The disk image includes all Asahi-specific packages +* All supported hardware is enabled and working from the first boot +* Disk images are reasonably up to date +* The install flow for all images is tested before release +* All disk images are thoroughly tested on multiple devices before release + +It should be noted that the disk image installation flow is a curiosity of early +bringup work that ended up sticking. While this installation method has its advantages, +it is not the way forward for workstation-class hardware and contributes to the stigma +of AArch64 devices being janky developers' toys. We heavily encourage distros +to invest time in building AArch64 bootable media with Apple Silicon support, +and leverage the reference installer's minimal UEFI environment. As mentioned above, +this aligns closer with user expectations and 40 years of precedence when dealing with +workstation-grade hardware. + +We are actively working on improving the tooling required to make bootable media installs +safer for users. Once we consider mainstream disk partitioning software and live media +installation tooling sufficiently foolproof on Apple Silicon devices, we _may_ reconsider +the need to support the image-based installation flow going forward. + +## Disendorsement +Through dilligent QA and attention to detail, Asahi Linux has +become well-regarded as one of the best desktop Linux experiences available. +This is a great source of pride for us, and we are determined to meet the high +user expectations that come with such a reputation. We expect officially +endorsed distros to strive to meet those same expectations. + +We hope that it will never be necessary to do so, but we may be required to +disendorse distros that are not meeting user or Asahi Linux expectations. +Disendorsed distros will be delisted from our documentation. Depending on the +circumstances, we may also discourage use of the disendorsed distro. + +Reasons for disendorsement may include: + +* A lack of official distro support for the Apple Silicon platform +* Frequent or recurring distro-specific issues that cannot be reproduced + on Fedora Asahi Remix, especially if such issues are not addressed in + a timely fashion +* Repeated failure to keep Asahi packages current +* Failure to keep installer disk images current (if image-based installation is offered) + diff --git a/mkdocs.yml b/mkdocs.yml index 16990713..b15ccab1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,8 @@ nav: - Devicetree bindings: sw/devicetree-bindings.md - Open OS ecosystem on Apple Silicon Macs: platform/open-os-interop.md - Userspace Audio Stack: sw/audio-userspace.md + - For distributions/OSes: + - Distro guidelines: alt/policy.md theme: name: material