feat: doc .envrc parameters & allow overriding toolchain

Signed-off-by: Oskar Manhart <52569953+oskardotglobal@users.noreply.github.com>

Author: oskardotglobal

.envrc.example

@@ -1 +1,7 @@
-use nix # --arg isIdea true --arg nixpkgs '<nixpkgs>'
+# isIdea: whether to write the current rust toolchain into `.idea/workspace.xml`, defaults to false
+# nixpkgs: the path to a nixpkgs checkout, defaults to a pinned version
+# mkToolchain: a function taking a fenix instance and returning a toolchain, defaults to `fenix: fenix.complete`
+use nix # \
+  # --arg isIdea true \
+  # --arg nixpkgs '<nixpkgs>' \
+  # --arg mkToolchain 'fenix: fenix.beta'

shell.nix

@@ -1,12 +1,15 @@
 {
   nixpkgs ? fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-25.05.tar.gz",
-  pkgs ? import nixpkgs { },
-  fenix ?
-    (import (fetchTarball "https://github.com/nix-community/fenix/archive/monthly.tar.gz") {
-      inherit pkgs;
-    }).complete,
+  fenix-src ? fetchTarball "https://github.com/nix-community/fenix/archive/monthly.tar.gz",
+
+  mkToolchain ? fenix: fenix.complete,
   isIdea ? false,
 }:
+let
+  pkgs = import nixpkgs { };
+  fenix = import fenix-src { inherit pkgs; };
+  toolchain = mkToolchain fenix;
+in
 pkgs.mkShell rec {
   buildInputs = with pkgs; [
     nixfmt-rfc-style
@@ -17,11 +20,11 @@ pkgs.mkShell rec {
 
     openssl
     pkg-config
-    fenix.toolchain
+    toolchain.toolchain
   ];
 
   RUST_BACKTRACE = 1;
-  RUST_SRC_PATH = "${fenix.rust-src}/lib/rustlib/src/rust/library";
+  RUST_SRC_PATH = "${toolchain.rust-src}/lib/rustlib/src/rust/library";
 
   shellHook =
     let
@@ -31,7 +34,7 @@ pkgs.mkShell rec {
     pkgs.lib.optionalString isIdea ''
       sed -i \
         -e "s|$(${xidel} .idea/workspace.xml -e '${pathFor "explicitPathToStdlib"}')|${RUST_SRC_PATH}|" \
-        -e "s|$(${xidel} .idea/workspace.xml -e '${pathFor "toolchainHomeDirectory"}')|${fenix.toolchain}/bin|" \
+        -e "s|$(${xidel} .idea/workspace.xml -e '${pathFor "toolchainHomeDirectory"}')|${toolchain.toolchain}/bin|" \
         .idea/workspace.xml
     '';
 }