Document using rust-overlay

Fixes #359

Author: drakon64

docs/src/content/docs/00_guides/80_using_a_rust_overlay.md

@@ -0,0 +1,78 @@
+---
+title: Using a Rust overlay
+---
+
+It's possible to use a Rust overlay such as `rust-overlay` with `crate2nix`.
+This can be used for pinning the Rust toolchain version, or to use a newer toolchain version than is available in Nixpkgs.
+
+In a flake with flake-parts:
+
+```nix
+# flake.nix
+{
+  # ...
+
+  inputs = {
+    flake-parts = {
+      url = "github:hercules-ci/flake-parts";
+      inputs.nixpkgs-lib.follows = "nixpkgs";
+    };
+    crate2nix.url = "github:nix-community/crate2nix";
+    # ...
+  };
+  
+  outputs =
+    inputs @ { self
+    , nixpkgs
+    , flake-parts
+    , rust-overlay
+    , crate2nix
+    , ...
+    }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-linux"
+        "aarch64-darwin"
+      ];
+
+      perSystem = { system, lib, inputs', ... }:
+        let
+          pkgs = import nixpkgs {
+            inherit system;
+            
+            overlays = [ rust-overlay.overlays.default ];
+          };
+          
+          buildRustCrateForPkgs =
+            crate:
+            pkgs.buildRustCrate.override {
+              rustc = pkgs.rust-bin.stable.latest.default;
+              cargo = pkgs.rust-bin.stable.latest.default;
+            };
+            
+          generatedCargoNix = inputs.crate2nix.tools.${system}.appliedCargoNix {
+            name = "rustnix";
+            src = ./.;
+          };
+          
+          cargoNix = import generatedCargoNix {
+            inherit pkgs buildRustCrateForPkgs;
+          };
+        in
+          rec {
+            checks = {
+              rustnix = cargoNix.rootCrate.build.override {
+                runTests = true;
+              };
+            };
+  
+            packages = {
+              rustnix = cargoNix.rootCrate.build;
+              default = packages.rustnix;
+            };
+          };
+    };
+}
+```

docs/src/content/docs/90_reference/90_CHANGELOG.md

@@ -5,7 +5,7 @@ description: A list of all major changes per version.
 
 ## 0.14.x - 0.15.0 (unreleased)
 
-TODO
+* [#359](https://github.com/nix-community/crate2nix/issues/359): Document using `rust-overlay`.
 
 ## 0.14.x - 0.14.1 (2024-06-30)