From bbc4b689273f8838133970aaa0d9b1a8e571706f Mon Sep 17 00:00:00 2001
From: Adam Chance <6444703+drakon64@users.noreply.github.com>
Date: Mon, 26 Aug 2024 22:46:11 +0100
Subject: [PATCH] Document using `rust-overlay` Fixes
 https://github.com/nix-community/crate2nix/issues/359

---
 .../docs/00_guides/80_using_a_rust_overlay.md | 78 +++++++++++++++++++
 .../content/docs/90_reference/90_CHANGELOG.md |  2 +-
 2 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/content/docs/00_guides/80_using_a_rust_overlay.md

diff --git a/docs/src/content/docs/00_guides/80_using_a_rust_overlay.md b/docs/src/content/docs/00_guides/80_using_a_rust_overlay.md
new file mode 100644
index 00000000..412ff33e
--- /dev/null
+++ b/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;
+            };
+          };
+    };
+}
+```
diff --git a/docs/src/content/docs/90_reference/90_CHANGELOG.md b/docs/src/content/docs/90_reference/90_CHANGELOG.md
index 01e1991c..c7864353 100644
--- a/docs/src/content/docs/90_reference/90_CHANGELOG.md
+++ b/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)