about summary refs log tree commit diff
path: root/nixpkgs/doc/languages-frameworks/rust.section.md
diff options
context:
space:
mode:
authorAlyssa Ross <hi@alyssa.is>2023-06-16 06:56:35 +0000
committerAlyssa Ross <hi@alyssa.is>2023-06-16 06:56:35 +0000
commit99fcaeccb89621dd492203ce1f2d551c06f228ed (patch)
tree41cb730ae07383004789779b0f6e11cb3f4642a3 /nixpkgs/doc/languages-frameworks/rust.section.md
parent59c5f5ac8682acc13bb22bc29c7cf02f7d75f01f (diff)
parent75a5ebf473cd60148ba9aec0d219f72e5cf52519 (diff)
downloadnixlib-99fcaeccb89621dd492203ce1f2d551c06f228ed.tar
nixlib-99fcaeccb89621dd492203ce1f2d551c06f228ed.tar.gz
nixlib-99fcaeccb89621dd492203ce1f2d551c06f228ed.tar.bz2
nixlib-99fcaeccb89621dd492203ce1f2d551c06f228ed.tar.lz
nixlib-99fcaeccb89621dd492203ce1f2d551c06f228ed.tar.xz
nixlib-99fcaeccb89621dd492203ce1f2d551c06f228ed.tar.zst
nixlib-99fcaeccb89621dd492203ce1f2d551c06f228ed.zip
Merge branch 'nixos-unstable' of https://github.com/NixOS/nixpkgs
Conflicts:
	nixpkgs/nixos/modules/config/console.nix
	nixpkgs/nixos/modules/services/mail/mailman.nix
	nixpkgs/nixos/modules/services/mail/public-inbox.nix
	nixpkgs/nixos/modules/services/mail/rss2email.nix
	nixpkgs/nixos/modules/services/networking/ssh/sshd.nix
	nixpkgs/pkgs/applications/networking/instant-messengers/dino/default.nix
	nixpkgs/pkgs/applications/networking/irc/weechat/default.nix
	nixpkgs/pkgs/applications/window-managers/sway/default.nix
	nixpkgs/pkgs/build-support/go/module.nix
	nixpkgs/pkgs/build-support/rust/build-rust-package/default.nix
	nixpkgs/pkgs/development/interpreters/python/default.nix
	nixpkgs/pkgs/development/node-packages/overrides.nix
	nixpkgs/pkgs/development/tools/b4/default.nix
	nixpkgs/pkgs/servers/dict/dictd-db.nix
	nixpkgs/pkgs/servers/mail/public-inbox/default.nix
	nixpkgs/pkgs/tools/security/pinentry/default.nix
	nixpkgs/pkgs/tools/text/unoconv/default.nix
	nixpkgs/pkgs/top-level/all-packages.nix
Diffstat (limited to 'nixpkgs/doc/languages-frameworks/rust.section.md')
-rw-r--r--nixpkgs/doc/languages-frameworks/rust.section.md385
1 files changed, 159 insertions, 226 deletions
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index e19783e29e6a..7d46bdbd4d48 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -13,9 +13,9 @@ into your `configuration.nix` or bring them into scope with `nix-shell -p rustc
 
 For other versions such as daily builds (beta and nightly),
 use either `rustup` from nixpkgs (which will manage the rust installation in your home directory),
-or use a community maintained [Rust overlay](#using-community-rust-overlays).
+or use [community maintained Rust toolchains](#using-community-maintained-rust-toolchains).
 
-## Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo}
+## `buildRustPackage`: Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo}
 
 Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
 
@@ -30,10 +30,10 @@ rustPlatform.buildRustPackage rec {
     owner = "BurntSushi";
     repo = pname;
     rev = version;
-    sha256 = "1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps";
+    hash = "sha256-+s5RBC3XSgb8omTbUNLywZnP6jSxZBKSS1BmXOjRF8M=";
   };
 
-  cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp";
+  cargoHash = "sha256-jtBw4ahSl88L0iuCXxQgZVm1EcboWRJMNtjxLVTtzts=";
 
   meta = with lib; {
     description = "A fast line-oriented regex search tool, similar to ag and ack";
@@ -50,6 +50,11 @@ package. `cargoHash256` is used for traditional Nix SHA-256 hashes,
 such as the one in the example above. `cargoHash` should instead be
 used for [SRI](https://www.w3.org/TR/SRI/) hashes. For example:
 
+Exception: If the application has cargo `git` dependencies, the `cargoHash`/`cargoSha256`
+approach will not work, and you will need to copy the `Cargo.lock` file of the application
+to nixpkgs and continue with the next section for specifying the options of the`cargoLock`
+section.
+
 ```nix
   cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
 ```
@@ -97,10 +102,10 @@ rustPlatform.buildRustPackage rec {
 
   src = fetchCrate {
     inherit pname version;
-    sha256 = "1mqaynrqaas82f5957lx31x80v74zwmwmjxxlbywajb61vh00d38";
+    sha256 = "sha256-aDQA4A5mScX9or3Lyiv/5GyAehidnpKKE0grhbP1Ctc=";
   };
 
-  cargoHash = "sha256-JmBZcDVYJaK1cK05cxx5BrnGWp4t8ca6FLUbvIot67s=";
+  cargoHash = "sha256-tbrTbutUs5aPSV+yE0IBUZAAytgmZV7Eqxia7g+9zRs=";
   cargoDepsName = pname;
 
   # ...
@@ -157,7 +162,7 @@ required to build a rust package. A simple fix is to use:
 
 ```nix
 postPatch = ''
-  cp ${./Cargo.lock} Cargo.lock
+  ln -s ${./Cargo.lock} Cargo.lock
 '';
 ```
 
@@ -186,6 +191,23 @@ added. To find the correct hash, you can first use `lib.fakeSha256` or
 `lib.fakeHash` as a stub hash. Building the package (and thus the
 vendored dependencies) will then inform you of the correct hash.
 
+For usage outside nixpkgs, `allowBuiltinFetchGit` could be used to
+avoid having to specify `outputHashes`. For example:
+
+```nix
+rustPlatform.buildRustPackage rec {
+  pname = "myproject";
+  version = "1.0.0";
+
+  cargoLock = {
+    lockFile = ./Cargo.lock;
+    allowBuiltinFetchGit = true;
+  };
+
+  # ...
+}
+```
+
 ### Cargo features {#cargo-features}
 
 You can disable default features using `buildNoDefaultFeatures`, and
@@ -319,6 +341,32 @@ The above are just guidelines, and exceptions may be granted on a case-by-case b
 However, please check if it's possible to disable a problematic subset of the
 test suite and leave a comment explaining your reasoning.
 
+This can be achieved with `--skip` in `checkFlags`:
+
+```nix
+rustPlatform.buildRustPackage {
+  /* ... */
+  checkFlags = [
+    # reason for disabling test
+    "--skip=example::tests:example_test"
+  ];
+}
+```
+
+#### Using `cargo-nextest` {#using-cargo-nextest}
+
+Tests can be run with [cargo-nextest](https://github.com/nextest-rs/nextest)
+by setting `useNextest = true`. The same options still apply, but nextest
+accepts a different set of arguments and the settings might need to be
+adapted to be compatible with cargo-nextest.
+
+```nix
+rustPlatform.buildRustPackage {
+  /* ... */
+  useNextest = true;
+}
+```
+
 #### Setting `test-threads` {#setting-test-threads}
 
 `buildRustPackage` will use parallel test threads by default,
@@ -368,13 +416,13 @@ rustPlatform.buildRustPackage rec {
 }
 ```
 
-## Compiling non-Rust packages that include Rust code {#compiling-non-rust-packages-that-include-rust-code}
+### Compiling non-Rust packages that include Rust code {#compiling-non-rust-packages-that-include-rust-code}
 
 Several non-Rust packages incorporate Rust code for performance- or
 security-sensitive parts. `rustPlatform` exposes several functions and
 hooks that can be used to integrate Cargo in non-Rust packages.
 
-### Vendoring of dependencies {#vendoring-of-dependencies}
+#### Vendoring of dependencies {#vendoring-of-dependencies}
 
 Since network access is not allowed in sandboxed builds, Rust crate
 dependencies need to be retrieved using a fetcher. `rustPlatform`
@@ -391,8 +439,8 @@ cargoDeps = rustPlatform.fetchCargoTarball {
 ```
 
 The `src` attribute is required, as well as a hash specified through
-one of the `sha256` or `hash` attributes. The following optional
-attributes can also be used:
+one of the `hash` attribute. The following optional attributes can
+also be used:
 
 * `name`: the name that is used for the dependencies tarball.  If
   `name` is not specified, then the name `cargo-deps` will be used.
@@ -434,7 +482,7 @@ added. To find the correct hash, you can first use `lib.fakeSha256` or
 `lib.fakeHash` as a stub hash. Building `cargoDeps` will then inform
 you of the correct hash.
 
-### Hooks {#hooks}
+#### Hooks {#hooks}
 
 `rustPlatform` provides the following hooks to automate Cargo builds:
 
@@ -458,16 +506,19 @@ you of the correct hash.
   `maturinBuildFlags`.
 * `cargoCheckHook`: run tests using Cargo. The build type for checks
   can be set using `cargoCheckType`. Features can be specified with
-  `cargoCheckNoDefaultFeaatures` and `cargoCheckFeatures`. Additional
+  `cargoCheckNoDefaultFeatures` and `cargoCheckFeatures`. Additional
   flags can be passed to the tests using `checkFlags` and
   `checkFlagsArray`. By default, tests are run in parallel. This can
   be disabled by setting `dontUseCargoParallelTests`.
+* `cargoNextestHook`: run tests using
+  [cargo-nextest](https://github.com/nextest-rs/nextest). The same
+  options for `cargoCheckHook` also applies to `cargoNextestHook`.
 * `cargoInstallHook`: install binaries and static/shared libraries
   that were built using `cargoBuildHook`.
 * `bindgenHook`: for crates which use `bindgen` as a build dependency, lets
   `bindgen` find `libclang` and `libclang` find the libraries in `buildInputs`.
 
-### Examples {#examples}
+#### Examples {#examples}
 
 #### Python package using `setuptools-rust` {#python-package-using-setuptools-rust}
 
@@ -484,7 +535,9 @@ directory of the `tokenizers` project's source archive, we use
 ```nix
 { fetchFromGitHub
 , buildPythonPackage
+, cargo
 , rustPlatform
+, rustc
 , setuptools-rust
 }:
 
@@ -502,16 +555,17 @@ buildPythonPackage rec {
   cargoDeps = rustPlatform.fetchCargoTarball {
     inherit src sourceRoot;
     name = "${pname}-${version}";
-    hash = "sha256-BoHIN/519Top1NUBjpB/oEMqi86Omt3zTQcXFWqrek0=";
+    hash = "sha256-miW//pnOmww2i6SOGbkrAIdc/JMDT4FJLqdMFojZeoY=";
   };
 
   sourceRoot = "source/bindings/python";
 
-  nativeBuildInputs = [ setuptools-rust ] ++ (with rustPlatform; [
-    cargoSetupHook
-    rust.cargo
-    rust.rustc
-  ]);
+  nativeBuildInputs = [
+    cargo
+    rustPlatform.cargoSetupHook
+    rustc
+    setuptools-rust
+  ];
 
   # ...
 }
@@ -539,7 +593,7 @@ buildPythonPackage rec {
 
   src = fetchPypi {
     inherit pname version;
-    sha256 = "1i1mx5y9hkyfi9jrrkcw804hmkcglxi6rmf7vin7jfnbr2bf4q64";
+    hash = "sha256-xGDilsjLOnls3MfVbGKnj80KCUCczZxlis5PmHzpNcQ=";
   };
 
   cargoDeps = rustPlatform.fetchCargoTarball {
@@ -579,7 +633,7 @@ buildPythonPackage rec {
     owner = "Qiskit";
     repo = "retworkx";
     rev = version;
-    sha256 = "11n30ldg3y3y6qxg3hbj837pnbwjkqw3nxq6frds647mmmprrd20";
+    hash = "sha256-11n30ldg3y3y6qxg3hbj837pnbwjkqw3nxq6frds647mmmprrd20=";
   };
 
   cargoDeps = rustPlatform.fetchCargoTarball {
@@ -596,105 +650,19 @@ buildPythonPackage rec {
 }
 ```
 
-## Compiling Rust crates using Nix instead of Cargo {#compiling-rust-crates-using-nix-instead-of-cargo}
+## `buildRustCrate`: Compiling Rust crates using Nix instead of Cargo {#compiling-rust-crates-using-nix-instead-of-cargo}
 
 ### Simple operation {#simple-operation}
 
 When run, `cargo build` produces a file called `Cargo.lock`,
 containing pinned versions of all dependencies. Nixpkgs contains a
-tool called `carnix` (`nix-env -iA nixos.carnix`), which can be used
-to turn a `Cargo.lock` into a Nix expression.
-
-That Nix expression calls `rustc` directly (hence bypassing Cargo),
-and can be used to compile a crate and all its dependencies. Here is
-an example for a minimal `hello` crate:
-
-```ShellSession
-$ cargo new hello
-$ cd hello
-$ cargo build
-     Compiling hello v0.1.0 (file:///tmp/hello)
-     Finished dev [unoptimized + debuginfo] target(s) in 0.20 secs
-$ carnix -o hello.nix --src ./. Cargo.lock --standalone
-$ nix-build hello.nix -A hello_0_1_0
-```
-
-Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
-
-```nix
-# Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ stdenv, buildRustCrate, fetchgit }:
-let kernel = stdenv.buildPlatform.parsed.kernel.name;
-    # ... (content skipped)
-in
-rec {
-  hello = f: hello_0_1_0 { features = hello_0_1_0_features { hello_0_1_0 = f; }; };
-  hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
-    crateName = "hello";
-    version = "0.1.0";
-    authors = [ "pe@pijul.org <pe@pijul.org>" ];
-    src = ./.;
-    inherit dependencies buildDependencies features;
-  };
-  hello_0_1_0 = { features?(hello_0_1_0_features {}) }: hello_0_1_0_ {};
-  hello_0_1_0_features = f: updateFeatures f (rec {
-        hello_0_1_0.default = (f.hello_0_1_0.default or true);
-    }) [ ];
-}
-```
+tool called `crate2Nix` (`nix-shell -p crate2nix`), which can be
+used to turn a `Cargo.lock` into a Nix expression.  That Nix
+expression calls `rustc` directly (hence bypassing Cargo), and can
+be used to compile a crate and all its dependencies.
 
-In particular, note that the argument given as `--src` is copied
-verbatim to the source. If we look at a more complicated
-dependencies, for instance by adding a single line `libc="*"` to our
-`Cargo.toml`, we first need to run `cargo build` to update the
-`Cargo.lock`. Then, `carnix` needs to be run again, and produces the
-following nix file:
-
-```nix
-# Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ stdenv, buildRustCrate, fetchgit }:
-let kernel = stdenv.buildPlatform.parsed.kernel.name;
-    # ... (content skipped)
-in
-rec {
-  hello = f: hello_0_1_0 { features = hello_0_1_0_features { hello_0_1_0 = f; }; };
-  hello_0_1_0_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
-    crateName = "hello";
-    version = "0.1.0";
-    authors = [ "pe@pijul.org <pe@pijul.org>" ];
-    src = ./.;
-    inherit dependencies buildDependencies features;
-  };
-  libc_0_2_36_ = { dependencies?[], buildDependencies?[], features?[] }: buildRustCrate {
-    crateName = "libc";
-    version = "0.2.36";
-    authors = [ "The Rust Project Developers" ];
-    sha256 = "01633h4yfqm0s302fm0dlba469bx8y6cs4nqc8bqrmjqxfxn515l";
-    inherit dependencies buildDependencies features;
-  };
-  hello_0_1_0 = { features?(hello_0_1_0_features {}) }: hello_0_1_0_ {
-    dependencies = mapFeatures features ([ libc_0_2_36 ]);
-  };
-  hello_0_1_0_features = f: updateFeatures f (rec {
-    hello_0_1_0.default = (f.hello_0_1_0.default or true);
-    libc_0_2_36.default = true;
-  }) [ libc_0_2_36_features ];
-  libc_0_2_36 = { features?(libc_0_2_36_features {}) }: libc_0_2_36_ {
-    features = mkFeatures (features.libc_0_2_36 or {});
-  };
-  libc_0_2_36_features = f: updateFeatures f (rec {
-    libc_0_2_36.default = (f.libc_0_2_36.default or true);
-    libc_0_2_36.use_std =
-      (f.libc_0_2_36.use_std or false) ||
-      (f.libc_0_2_36.default or false) ||
-      (libc_0_2_36.default or false);
-  }) [];
-}
-```
-
-Here, the `libc` crate has no `src` attribute, so `buildRustCrate`
-will fetch it from [crates.io](https://crates.io). A `sha256`
-attribute is still needed for Nix purity.
+See [`crate2nix`'s documentation](https://github.com/kolloch/crate2nix#known-restrictions)
+for instructions on how to use it.
 
 ### Handling external dependencies {#handling-external-dependencies}
 
@@ -802,22 +770,7 @@ general. A number of other parameters can be overridden:
   };
   ```
 
-### Features {#features}
-
-One can also supply features switches. For example, if we want to
-compile `diesel_cli` only with the `postgres` feature, and no default
-features, we would write:
-
-```nix
-(callPackage ./diesel.nix {}).diesel {
-  default = false;
-  postgres = true;
-}
-```
-
-Where `diesel.nix` is the file generated by Carnix, as explained above.
-
-## Setting Up `nix-shell` {#setting-up-nix-shell}
+### Setting Up `nix-shell` {#setting-up-nix-shell}
 
 Oftentimes you want to develop code from within `nix-shell`. Unfortunately
 `buildRustCrate` does not support common `nix-shell` operations directly
@@ -861,31 +814,61 @@ $ cargo build
 $ cargo test
 ```
 
-### Controlling Rust Version Inside `nix-shell` {#controlling-rust-version-inside-nix-shell}
+## Using community maintained Rust toolchains {#using-community-maintained-rust-toolchains}
+
+::: {.note}
+Note: The following projects cannot be used within nixpkgs since [IFD](#ssec-import-from-derivation) is disallowed.
+To package things that require Rust nightly, `RUSTC_BOOTSTRAP = true;` can sometimes be used as a hack.
+:::
+
+There are two community maintained approaches to Rust toolchain management:
+- [oxalica's Rust overlay](https://github.com/oxalica/rust-overlay)
+- [fenix](https://github.com/nix-community/fenix)
+
+Despite their names, both projects provides a similar set of packages and overlays under different APIs.
+
+Oxalica's overlay allows you to select a particular Rust version without you providing a hash or a flake input,
+but comes with a larger git repository than fenix.
+
+Fenix also provides rust-analyzer nightly in addition to the Rust toolchains.
+
+Both oxalica's overlay and fenix better integrate with nix and cache optimizations.
+Because of this and ergonomics, either of those community projects
+should be preferred to the Mozilla's Rust overlay ([nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla)).
+
+The following documentation demonstrates examples using fenix and oxalica's Rust overlay
+with `nix-shell` and building derivations. More advanced usages like flake usage
+are documented in their own repositories.
+
+### Using Rust nightly with `nix-shell` {#using-rust-nightly-with-nix-shell}
 
-To control your rust version (i.e. use nightly) from within `shell.nix` (or
-other nix expressions) you can use the following `shell.nix`
+Here is a simple `shell.nix` that provides Rust nightly (default profile) using fenix:
 
 ```nix
-# Latest Nightly
-with import <nixpkgs> {};
-let src = fetchFromGitHub {
-      owner = "mozilla";
-      repo = "nixpkgs-mozilla";
-      # commit from: 2019-05-15
-      rev = "9f35c4b09fd44a77227e79ff0c1b4b6a69dff533";
-      sha256 = "18h0nvh55b5an4gmlgfbvwbyqj91bklf1zymis6lbdh75571qaz0";
-   };
+with import <nixpkgs> { };
+let
+  fenix = callPackage
+    (fetchFromGitHub {
+      owner = "nix-community";
+      repo = "fenix";
+      # commit from: 2023-03-03
+      rev = "e2ea04982b892263c4d939f1cc3bf60a9c4deaa1";
+      hash = "sha256-AsOim1A8KKtMWIxG+lXh5Q4P2bhOZjoUhFWJ1EuZNNk=";
+    })
+    { };
 in
-with import "${src.out}/rust-overlay.nix" pkgs pkgs;
-stdenv.mkDerivation {
+mkShell {
   name = "rust-env";
-  buildInputs = [
-    # Note: to use stable, just replace `nightly` with `stable`
-    latest.rustChannels.nightly.rust
+  nativeBuildInputs = [
+    # Note: to use stable, just replace `default` with `stable`
+    fenix.default.toolchain
 
-    # Add some extra dependencies from `pkgs`
-    pkg-config openssl
+    # Example Build-time Additional Dependencies
+    pkg-config
+  ];
+  buildInputs = [
+    # Example Run-time Additional Dependencies
+    openssl
   ];
 
   # Set Environment Variables
@@ -893,116 +876,66 @@ stdenv.mkDerivation {
 }
 ```
 
-Now run:
+Save this to `shell.nix`, then run:
 
 ```ShellSession
 $ rustc --version
-rustc 1.26.0-nightly (188e693b3 2018-03-26)
+rustc 1.69.0-nightly (13471d3b2 2023-03-02)
 ```
 
 To see that you are using nightly.
 
-## Using community Rust overlays {#using-community-rust-overlays}
-
-There are two community maintained approaches to Rust toolchain management:
-- [oxalica's Rust overlay](https://github.com/oxalica/rust-overlay)
-- [fenix](https://github.com/nix-community/fenix)
-
-Oxalica's overlay allows you to select a particular Rust version and components.
-See [their documentation](https://github.com/oxalica/rust-overlay#rust-overlay) for more
-detailed usage.
+Oxalica's Rust overlay has more complete examples of `shell.nix` (and cross compilation) under its
+[`examples` directory](https://github.com/oxalica/rust-overlay/tree/e53e8853aa7b0688bc270e9e6a681d22e01cf299/examples).
 
-Fenix is an alternative to `rustup` and can also be used as an overlay.
+### Using Rust nightly in a derivation with `buildRustPackage` {#using-rust-nightly-in-a-derivation-with-buildrustpackage}
 
-Both oxalica's overlay and fenix better integrate with nix and cache optimizations.
-Because of this and ergonomics, either of those community projects
-should be preferred to the Mozilla's Rust overlay (`nixpkgs-mozilla`).
+You can also use Rust nightly to build rust packages using `makeRustPlatform`.
+The below snippet demonstrates invoking `buildRustPackage` with a Rust toolchain from oxalica's overlay:
 
-### How to select a specific `rustc` and toolchain version {#how-to-select-a-specific-rustc-and-toolchain-version}
-
-You can consume the oxalica overlay and use it to grab a specific Rust toolchain version.
-Here is an example `shell.nix` showing how to grab the current stable toolchain:
 ```nix
-{ pkgs ? import <nixpkgs> {
-    overlays = [
-      (import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
-    ];
-  }
-}:
-pkgs.mkShell {
-  nativeBuildInputs = with pkgs; [
-    pkg-config
-    rust-bin.stable.latest.minimal
-  ];
-}
-```
-
-You can try this out by:
-1. Saving that to `shell.nix`
-2. Executing `nix-shell --pure --command 'rustc --version'`
-
-As of writing, this prints out `rustc 1.56.0 (09c42c458 2021-10-18)`.
-
-### How to use an overlay toolchain in a derivation  {#how-to-use-an-overlay-toolchain-in-a-derivation}
-
-You can also use an overlay's Rust toolchain with `buildRustPackage`.
-The below snippet demonstrates invoking `buildRustPackage` with an oxalica overlay selected Rust toolchain:
-```nix
-with import <nixpkgs> {
+with import <nixpkgs>
+{
   overlays = [
     (import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
   ];
 };
+let
+  rustPlatform = makeRustPlatform {
+    cargo = rust-bin.stable.latest.minimal;
+    rustc = rust-bin.stable.latest.minimal;
+  };
+in
 
 rustPlatform.buildRustPackage rec {
   pname = "ripgrep";
   version = "12.1.1";
-  nativeBuildInputs = [
-    rust-bin.stable.latest.minimal
-  ];
 
   src = fetchFromGitHub {
     owner = "BurntSushi";
     repo = "ripgrep";
     rev = version;
-    sha256 = "1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps";
+    hash = "sha256-+s5RBC3XSgb8omTbUNLywZnP6jSxZBKSS1BmXOjRF8M=";
   };
 
-  cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp";
+  cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
+
+  doCheck = false;
 
   meta = with lib; {
     description = "A fast line-oriented regex search tool, similar to ag and ack";
     homepage = "https://github.com/BurntSushi/ripgrep";
-    license = licenses.unlicense;
-    maintainers = [ maintainers.tailhook ];
+    license = with licenses; [ mit unlicense ];
+    maintainers = with maintainers; [ tailhook ];
   };
 }
 ```
 
 Follow the below steps to try that snippet.
-1. create a new directory
 1. save the above snippet as `default.nix` in that directory
-1. cd into that directory and run `nix-build`
-
-### Rust overlay installation {#rust-overlay-installation}
-
-You can use this overlay by either changing your local nixpkgs configuration,
-or by adding the overlay declaratively in a nix expression,  e.g. in `configuration.nix`.
-For more information see [the manual on installing overlays](#sec-overlays-install).
-
-### Declarative Rust overlay installation {#declarative-rust-overlay-installation}
-
-This snippet shows how to use oxalica's Rust overlay.
-Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:
-
-```nix
-{ pkgs ? import <nixpkgs> {
-    overlays = [
-      (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
-      # Further overlays go here
-    ];
-  };
-};
-```
+2. cd into that directory and run `nix-build`
 
-Note that this will fetch the latest overlay version when rebuilding your system.
+Fenix also has examples with `buildRustPackage`,
+[crane](https://github.com/ipetkov/crane),
+[naersk](https://github.com/nix-community/naersk),
+and cross compilation in its [Examples](https://github.com/nix-community/fenix#examples) section.