# Rust {#rust}

To install the rust compiler and cargo put

```nix
{
  environment.systemPackages = [
    rustc
    cargo
  ];
}
```

into your `configuration.nix` or bring them into scope with `nix-shell -p rustc cargo`.

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 [community maintained Rust toolchains](#using-community-maintained-rust-toolchains).

## `buildRustPackage`: Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo}

Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:

```nix
{
  lib,
  fetchFromGitHub,
  rustPlatform,
}:

rustPlatform.buildRustPackage (finalAttrs: {
  pname = "ripgrep";
  version = "14.1.1";

  src = fetchFromGitHub {
    owner = "BurntSushi";
    repo = "ripgrep";
    tag = finalAttrs.version;
    hash = "sha256-gyWnahj1A+iXUQlQ1O1H1u7K5euYQOld9qWm99Vjaeg=";
  };

  cargoHash = "sha256-9atn5qyBDy4P6iUoHFhg+TV6Ur71fiah4oTJbBMeEy4=";

  meta = {
    description = "Fast line-oriented regex search tool, similar to ag and ack";
    homepage = "https://github.com/BurntSushi/ripgrep";
    license = lib.licenses.unlicense;
    maintainers = [ ];
  };
})
```

`buildRustPackage` requires a `cargoHash` attribute, computed over all crate sources of this package.

::: {.warning}
`cargoSha256` is already deprecated, and is subject to removal in favor of
`cargoHash` which supports [SRI](https://www.w3.org/TR/SRI/) hashes.

If you are still using `cargoSha256`, you can simply replace it with
`cargoHash` and recompute the hash, or convert the original sha256 to SRI
hash using `nix-hash --to-sri --type sha256 "<original sha256>"`.
:::

```nix
{
  cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
}
```

If this method does not work, you can resort to copying the `Cargo.lock` file into nixpkgs
and importing it as described in the [next section](#importing-a-cargo.lock-file).

Both types of hashes are permitted when contributing to nixpkgs. The
Cargo hash is obtained by inserting a fake checksum into the
expression and building the package once. The correct checksum can
then be taken from the failed build. A fake hash can be used for
`cargoHash` as follows:

```nix
{
  cargoHash = lib.fakeHash;
}
```

Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
best practices guide, Rust applications should always commit the `Cargo.lock`
file in git to ensure a reproducible build. However, a few packages do not, and
Nix depends on this file, so if it is missing you can use `cargoPatches` to
apply it in the `patchPhase`. Consider sending a PR upstream with a note to the
maintainer describing why it's important to include in the application.

The fetcher will verify that the `Cargo.lock` file is in sync with the `src`
attribute, and fail the build if not. It will also will compress the vendor
directory into a tar.gz archive.

The tarball with vendored dependencies contains a directory with the
package's `name`, which is normally composed of `pname` and
`version`. This means that the vendored dependencies hash
(`cargoHash`) is dependent on the package name and
version. The `cargoDepsName` attribute can be used to use another name
for the directory of vendored dependencies. For example, the hash can
be made invariant to the version by setting `cargoDepsName` to
`pname`:

```nix
rustPlatform.buildRustPackage (finalAttrs: {
  pname = "broot";
  version = "1.2.0";

  src = fetchCrate {
    inherit (finalAttrs) pname version;
    hash = "sha256-aDQA4A5mScX9or3Lyiv/5GyAehidnpKKE0grhbP1Ctc=";
  };

  cargoHash = "sha256-iDYh52rj1M5Uupvbx2WeDd/jvQZ+2A50V5rp5e2t7q4=";
  cargoDepsName = finalAttrs.pname;

  # ...
})
```

### Importing a `Cargo.lock` file {#importing-a-cargo.lock-file}

Using a vendored hash (`cargoHash`) is tedious when using
`buildRustPackage` within a project, since it requires that the hash