add option to change the way experimental Mesa is installed

nix/m1-support/mesa/default.nix

@@ -1,26 +1,45 @@
 { config, pkgs, lib, ... }:
 {
   config = let
-    mesaAsahi = pkgs.callPackage ./package.nix { };
-  in lib.mkIf config.hardware.asahi.useExperimentalGPUDriver {
-    # some programs (like Plasma Wayland) are broken if the version of
-    # Mesa they link against is different to the one driving the
-    # graphics card. replace the Mesa linked into system packages with
-    # the Asahi one without rebuilding the world. it's unclear if the
-    # issue is simply slightly different Mesa versions or the
-    # modifications required for the Apple GPU but the replacement is
-    # safe enough and this is all experimental anyway.
-    system.replaceRuntimeDependencies = [
-      { original = pkgs.mesa;
-        replacement = mesaAsahi;
-      }
-    ];
-
-    hardware.opengl.package = mesaAsahi.drivers;
-
-    # required for GPU kernel driver
-    hardware.asahi.addEdgeKernelConfig = true;
-  };
+    isMode = mode: (config.hardware.asahi.useExperimentalGPUDriver
+        && config.hardware.asahi.experimentalGPUInstallMode == mode);
+  in lib.mkMerge [
+    (lib.mkIf config.hardware.asahi.useExperimentalGPUDriver {
+      # make the Asahi Mesa available via an overlay so the user has access to it
+      # (being careful not to create infinite recursion if the user wants to overlay
+      # it over the original Mesa)
+      nixpkgs.overlays = [
+        (final: prev: {
+          mesa-asahi-edge = final.callPackage ./package.nix { inherit (prev) mesa; };
+        })
+      ];
+
+      # install the drivers
+      hardware.opengl.package = pkgs.mesa-asahi-edge.drivers;
+
+      # required for GPU kernel driver
+      hardware.asahi.addEdgeKernelConfig = true;
+    })
+    (lib.mkIf (isMode "replace") {
+      # replace the Mesa linked into system packages with the Asahi version
+      # without rebuilding them to avoid rebuilding the world.
+      system.replaceRuntimeDependencies = [
+        { original = pkgs.mesa;
+          replacement = pkgs.mesa-asahi-edge;
+        }
+      ];
+    })
+    (lib.mkIf (isMode "overlay") {
+      # replace the Mesa used in Nixpkgs with the Asahi version using an overlay,
+      # which requires rebuilding the world but ensures it is done faithfully
+      # (and in a way compatible with pure evaluation)
+      nixpkgs.overlays = [
+        (final: prev: {
+          mesa = final.mesa-asahi-edge;
+        })
+      ];
+    })
+  ];
 
   options.hardware.asahi.useExperimentalGPUDriver = lib.mkOption {
     type = lib.types.bool;
@@ -31,4 +50,21 @@
       Do not report issues using this driver under NixOS to the Asahi project.
     '';
   };
+
+  options.hardware.asahi.experimentalGPUInstallMode = lib.mkOption {
+    type = lib.types.enum [ "driver" "replace" "overlay" ];
+    default = "replace";
+    description = ''
+      Mode to use to install the experimental GPU driver into the system.
+
+      driver: install only as a driver, do not replace system Mesa.
+        Causes issues with certain programs like Plasma Wayland.
+
+      replace (default): use replaceRuntimeDependencies to replace system Mesa with Asahi Mesa.
+        Does not work in pure evaluation context (i.e. in flakes by default).
+
+      overlay: overlay system Mesa with Asahi Mesa
+        Requires rebuilding the world.
+    '';
+  };
 }