Additional bootstrapper safety checks (#26242)

* Unset `grep` options to prevent issues with forcing colour.
* Treat `musl`-based Linux distros are unsupported.
* Fix bootstrapper tests

.github/workflows/bootstrap_testing.yml

@@ -49,14 +49,14 @@ jobs:
           - debian:11
           - debian:12
           - debian:13
-          - ubuntu:20.04
           - ubuntu:22.04
           - ubuntu:24.04
+          - ubuntu:26.04
 
           # RHEL/CentOS/Fedora based
-          - fedora:41
           - fedora:42
           - fedora:43
+          - fedora:44
           - rockylinux:8
           - rockylinux:9
           - rockylinux/rockylinux:10
@@ -64,7 +64,7 @@ jobs:
           - almalinux:9
           - almalinux:10
 
-          # OpenSUSE based (we skip Tumbleweed as it has issues with package versions between pattern installs and other dependencies preinstalled into the base container)
+          # OpenSUSE based (we skip Tumbleweed as it has issues with package mirrors regularly being out of date)
           - opensuse/leap:latest
 
           # Gentoo-based
@@ -96,7 +96,7 @@ jobs:
                   ;;
                 *suse*)
                   zypper --non-interactive refresh
-                  zypper --non-interactive install sudo git shadow findutils  # findutils=xargs
+                  zypper --non-interactive install sudo git shadow findutils tar  # findutils=xargs
                   ;;
                 *gentoo*)
                   emerge-webrsync

docs/newbs_getting_started.md

@@ -75,6 +75,8 @@ curl -fsSL https://install.qmk.fm | sh
 
 ::: info
 Many Linux distributions are supported, but not all. Mainstream distributions will have best success -- if possible, choose either Debian or its derivatives (such as Ubuntu, or Mint), CentOS or its derivatives (such as Fedora, or Rocky Linux), and Arch or its derivatives (such as Manjaro, or CachyOS).
+
+**The standard QMK build environment installed below does not support `musl`-based Linux distributions.**
 :::
 
 Install the QMK CLI by running:

util/env-bootstrap.sh

@@ -39,6 +39,10 @@
 { # this ensures the entire script is downloaded #
     set -eu
 
+    # Prevent user grep settings from injecting flags (e.g. --color=always) that
+    # corrupt captured output and break pattern matching throughout this script.
+    unset GREP_OPTIONS GREP_COLOR GREP_COLORS
+
     BOOTSTRAP_TMPDIR="$(mktemp -d /tmp/qmk-bootstrap-failure.XXXXXX)"
     trap 'rm -rf "$BOOTSTRAP_TMPDIR" >/dev/null 2>&1 || true' EXIT
     FAILURE_FILE="${BOOTSTRAP_TMPDIR}/fail"
@@ -225,11 +229,28 @@ __EOT__
         macos) echo "zstd clang-format make hidapi libusb dos2unix git" ;;
         windows) echo "base-devel: zstd:p toolchain:p clang:p hidapi:p dos2unix: git: unzip:" ;;
         linux)
+            if ldd --version 2>&1 | grep -qi musl; then
+                echo >&2
+                echo "Sorry, QMK's pre-built toolchains are compiled against glibc and will not run on musl-based Linux distributions." >&2
+                echo >&2
+                echo "Try using a glibc-based distribution, or use Docker instead:" >&2
+                echo "  - https://docs.qmk.fm/newbs_getting_started#set-up-your-environment" >&2
+                echo "  - https://docs.qmk.fm/#/getting_started_docker" >&2
+                echo >&2
+                echo "If you cannot use a compatible distro, you can try installing the \`qmk\` Python package manually using \`pip\`, most likely requiring a virtual environment:" >&2
+                echo "  % python3 -m pip install qmk" >&2
+                echo >&2
+                echo "All other dependencies will need to be installed manually, such as make, git, AVR and ARM toolchains, and associated flashing utilities." >&2
+                echo >&2
+                echo "**NOTE**: QMK does not provide official support for musl-based environments. Here be dragons, you are on your own." >&2
+                signal_execution_failure
+                return
+            fi
             case $(grep ID /etc/os-release) in
             *arch* | *manjaro* | *cachyos*) echo "zstd base-devel clang diffutils wget unzip zip hidapi dos2unix git" ;;
             *debian* | *ubuntu*) echo "zstd build-essential clang-format diffutils wget unzip zip libhidapi-hidraw0 dos2unix git" ;;
             *fedora*) echo "zstd clang diffutils which gcc git wget unzip zip hidapi dos2unix libusb-devel libusb1-devel libusb-compat-0.1-devel libusb0-devel git epel-release" ;;
-            *suse*) echo "zstd clang diffutils wget unzip zip libhidapi-hidraw0 dos2unix git libusb-1_0-devel gzip which" ;;
+            *suse*) echo "zstd make gcc binutils clang diffutils wget unzip zip libhidapi-hidraw0 dos2unix git libusb-1_0-devel gzip which" ;;
             *gentoo*) echo "zstd sys-apps/diffutils wget unzip zip dev-libs/hidapi dos2unix dev-vcs/git dev-libs/libusb app-arch/gzip which" ;;
             *)
                 echo >&2
@@ -321,25 +342,24 @@ __EOT__
             *fedora*)
                 echo "It will also install the following system packages using 'dnf':" >&2
                 print_package_manager_deps_and_delay
-                # Some RHEL-likes need EPEL for hidapi
+                # Some RHEL-likes need EPEL for hidapi and libusb packages
                 $(nsudo) dnf -y install epel-release 2>/dev/null || true
-                # RHEL-likes have some naming differences in libusb packages, so manually handle those
+                # RHEL-likes have naming differences in libusb/hidapi packages; try each individually
-                $(nsudo) dnf -y install $(get_package_manager_deps | tr ' ' '\n' | grep -v 'epel-release' | grep -v libusb | tr '\n' ' ')
+                $(nsudo) dnf -y install $(get_package_manager_deps | tr ' ' '\n' | grep -v 'epel-release' | grep -v libusb | grep -v hidapi | tr '\n' ' ')
-                for pkg in $(get_package_manager_deps | tr ' ' '\n' | grep libusb); do
+                for pkg in $(get_package_manager_deps | tr ' ' '\n' | grep -E 'libusb|hidapi'); do
                     $(nsudo) dnf -y install "$pkg" 2>/dev/null || true
                 done
                 ;;
             *opensuse* | *suse*)
-                echo "It will also install development tools as well as the following system packages using 'zypper':" >&2
+                echo "It will also install the following system packages using 'zypper':" >&2
                 print_package_manager_deps_and_delay
                 $(nsudo) zypper --non-interactive refresh
-                $(nsudo) zypper --non-interactive install -t pattern devel_basis devel_C_C++
                 $(nsudo) zypper --non-interactive install $(get_package_manager_deps)
                 ;;
             *gentoo*)
                 echo "It will also install the following system packages using 'emerge':" >&2
                 print_package_manager_deps_and_delay
-                $(nsudo) emerge --sync
+                $(nsudo) emerge-webrsync
                 $(nsudo) emerge --noreplace --ask=n $(get_package_manager_deps | tr ' ' '\n') || signal_execution_failure
                 exit_if_execution_failed
                 ;;