Welcome

fuel.nix provides an easy, reliable way of using Fuel tools.

Each night at midnight (UTC) the fuel.nix repo is automatically updated with the latest stable and nightly releases of all fuel packages. Builds are tested and cached for both Linux and macOS systems.

Check out the Quick Start to dive in!

Quick Start

Let's install both Nix and the latest full suite of Fuel tools in just two commands.

Install Nix

Nix is a package manager with a focus on reproducibility and reliability. We can install it and enable the Fuel Labs binary cache with the following:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix/tag/v0.20.2 | sh -s -- install --extra-conf "extra-substituters = https://fuellabs.cachix.org" --extra-conf "extra-trusted-public-keys = fuellabs.cachix.org-1:3gOmll82VDbT7EggylzOVJ6dr0jgPVU/KMN6+Kf8qx8="

Note: For more details on Nix installation or how to configure an existing Nix or NixOS installation, see the detailed Nix Setup chapter.

Install Fuel

After installing Nix, open a new terminal and install the stable Fuel toolchain in a temporary shell with the following:

nix shell github:fuellabs/fuel.nix#fuel-testnet

This will download the latest release of fuel-core, forc, compatible with the testnet network and a suite of other tools from the Fuel Labs cache into the local /nix/store cache and "install" them to PATH for the duration of the current shell.

Let's check installation worked:

$ fuel-core --version
fuel-core 0.26.0

$ forc --version
forc 0.60.0

Note: If you have previously installed Fuel tools using cargo, fuelup or some other means, it is recommended to double check your PATH to make sure you are using those installed by Nix.

echo $PATH

Your console will always use the first version of an executable that appears in your PATH.

Now we're ready to build with Fuel!

We can exit the current shell to remove the tools from our PATH as if they were never installed.

Diving Deeper

To find out how to install tools persistently for the current user, how to install different toolchain channels (nightly, testnet, etc), how to install individual components, along with a whole suite of other options, see the Packages chapter.

For more details on installing Nix or configuring an existing Nix or NixOS installation, see the Nix Setup chapter.

If you are content with the installation, see the Documentation Portal for more details on how to build with Fuel!

Nix Setup

Nix is a package manager with a focus on reproducibility and reliability. Fuel Labs leverages Nix to provide a simple way to natively install the ecosystem tooling along with any necessary system dependencies and environment setup.

This chapter provides a more detailed look at the Nix installation process, describes how to setup an existing Nix configuration, and covers how to uninstall Nix and its installed packages if necessary.

Install Nix

To recap our Quick Start, we can install Nix with the following command:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix/tag/v0.20.2 | sh -s -- install --extra-conf "extra-substituters = https://fuellabs.cachix.org" --extra-conf "extra-trusted-public-keys = fuellabs.cachix.org-1:3gOmll82VDbT7EggylzOVJ6dr0jgPVU/KMN6+Kf8qx8="

This uses the nix-installer tool by Determinate Systems to install Nix with the flakes and nix-command features enabled, and provides --extra-conf flags that enable the Fuel Labs binary cache.

Note: Without a binary cache, Nix will build everything from source on first use. This can take a long time! The fuel.nix repo CI builds all channels (published, nightly, milestones) and provides a cache so you don't have to.

The installer will first present an installation plan before prompting to continue. Feel free to review or prompt for further explanation before proceeding with installation.

After continuing, Nix installation should complete within a few seconds. Be sure to open a new terminal before using nix.

Configuring an Existing Nix Installation

If you're an existing Nix user you can enable the necessary features along with the Fuel Labs binary cache with the following additions to your Nix configuration (/etc/nix/nix.conf):

experimental-features = nix-command flakes
extra-substituters = https://fuellabs.cachix.org
extra-trusted-public-keys = fuellabs.cachix.org-1:3gOmll82VDbT7EggylzOVJ6dr0jgPVU/KMN6+Kf8qx8=

Configuring NixOS

Similarly, if you're an existing NixOS user, you can update your nixos configuration with the following:

{
  nix = {
    settings = {
      experimental-features = ["nix-command" "flakes"];
      extra-substituters = ["https://fuellabs.cachix.org"];
      extra-trusted-public-keys = [
        "fuellabs.cachix.org-1:3gOmll82VDbT7EggylzOVJ6dr0jgPVU/KMN6+Kf8qx8="
      ];
    };
  };
}

Trouble Shooting

Nix command not available

The daemon that makes nix available to your shell is not run automatically after installation. You'll need to either manually start it in your shell instance with nix daemon or open a new instance of your shell. If it persists, log out, log back in and open a new terminal.

Nix isn't using the Fuel cache

In some cases, usually in existing nix installations, nix may have trouble finding or using the cache. This could happen for a few reasons:

Confirm you are a trusted user:

The user the request is coming from may not be a trusted user, in which case some permissions may be missing to use parts of the configuration. There is a great example of this in the Nix discourse which can be found here that also provides a solution if you want certain features available to untrusted users.

The extra-substitutors section is overlooked:

extra-substitutors appends additional caches to those already specified by substitutors, and will silently ignore them when they are attempted to be used by unprivileged users. If the output of nix show-config does not show the Fuel cache in extra-substitutors after confirming you are a trusted user, you may need to restart your shell. If this still does not solve the issue, try adding the Fuel cachix link to substitutors instead, separating any existing substitutors by whitespace.

Negative caching:

If you ran into any of the previous problems, which made your system build a derivation from source, you may experience negative caching in which case you'll need to reset the lookup cache that nix uses to check if a cache doesn't exist.

If a problem persists after trying the above please open an issue.

Uninstall Everything

If you installed Nix using the Determinate Systems nix-installer tool as described in this guide, you can uninstall Nix along with all nix-installed packages with the following:

/nix/nix-installer uninstall

Packages

The fuel.nix flake provides the following packages:

Running Packages

You can run any of the above programs without installing them like so:

nix run github:fuellabs/fuel.nix#fuel-core

To run the latest nightly for a package, add -nightly to the end, e.g.

nix run github:fuellabs/fuel.nix#forc-nightly

Similarly, run the version of a package from a milestone with -<milestone>, e.g.

nix run github:fuellabs/fuel.nix#forc-lsp-testnet

nix run github:fuellabs/fuel.nix#forc-wallet-testnet

Temporary Shells

To enter a temporary shell with all of the fuel packages available on $PATH, you can use the following:

nix shell github:fuellabs/fuel.nix#fuel

When you exit the shell the tools will no longer be on the PATH.

The nix shell command is useful for maintaining isolated, temporary environments and to avoid endlessly polluting your PATH with different versions. E.g. in the following, we trivially switch between a stable fuel toolchain and nightly toolchain:

$ nix shell github:fuellabs/fuel.nix#fuel

# All latest stable `fuel` packages on `PATH`.

$ exit

# No fuel packages on `PATH`

$ nix shell github:fuellabs/fuel.nix#fuel-nightly

# All latest nightly `fuel` packages on `PATH`.

$ exit

# No fuel packages on `PATH`

$ nix shell github:fuellabs/fuel.nix#fuel-testnet

# All testnet milestone `fuel` packages on `PATH`.

Installing Packages

To install fuel packages persistently for the current user:

nix profile install github:fuellabs/fuel.nix#fuel

To view whats installed for the current user:

nix profile list

To upgrade all installed packages to their latest versions:

nix profile upgrade

You can optionally specify a specific package to upgrade.

To remove an installed package:

nix profile remove 3

where 3 is the index of the package when running nix profile list.

For more options around managing nix user profiles, see the docs.

NOTE: If a previous version of Nix was installed on the system, the nix profile command may not work due to an old symlink being present in $HOME. See this issue. If you encounter this issue, you can remedy it by deleting the ~/.nix-profile symlink so that the nix profile commands can recreate it with the correct path.

Specifying Versions

To specify a specific version, append the semver or nightly date to the end:

nix run github:fuellabs/fuel.nix#forc-fmt-0-24-1

nix run github:fuellabs/fuel.nix#forc-fmt-0-24-3-nightly-2022-09-14

Note: that when building an older version or nightly, they may no longer be available in the binary cache and may need to be rebuilt!

Nix Power Users

fuel.nix offers some tools that may be more useful for existing Nix and NixOS power users.

This chapter is targeted towards more experienced Nix users who use Nix to configure their home or NixOS systems (e.g. using home-manager or NixOS configuration).

Dev Shells

fuel.nix also features a few devShells that make it easy to drop into a development shell for working on the fuel packages. They allow you to drop into a temporary shell with all the tools and environment variables required to build the various fuel projects yourself.

You can enter a temporary dev shell like so:

nix develop github:fuellabs/fuel.nix#fuel-dev

Note that you can also enter a dev shell for individual packages. E.g. the following enters a dev shell with the required environment for working on the Sway language server implementation

nix develop github:fuellabs/fuel.nix#forc-lsp

Currently the vim plugin still needs to be installed separately. See the Overlays chapter and the Nix Vim wiki for more details.

Note: While these devShells might be useful to get started on developing fuel packages, ideally each upstream package would provide its own devShell so that it may iterate on its own shell with more freedom (without editing these downstream devShells).

Overlays

Two nixpkgs overlays are provided (fuel and fuel-nightly) that allow for "merging" the set of packages provided by this flake with nixpkgs.

Note that this makes the sway-vim plugin accessible via the vimPlugins set following the nixpkgs convention, e.g. nixpkgs.vimPlugins.sway-vim.

Editor Plugins

Currently this flake and its overlay only provide the sway-vim Vim plugin.

Contributions adding support for other editors/IDE plugins are more than welcome!

In the meantime, you can install the Sway VS Code plugin from the marketplace as per usual.

Contributing

This chapter will cover the internals of fuel.nix, how it works, and how to contribute!

Internals

At a very high level, fuel.nix does the following:

1. Generate unique "manifests" for each version of each package every night at 00:00 UTC under the ./manifests directory using a CI action that runs the ./scripts/refresh-manifests.sh script.
2. Provide package flake outputs (e.g. forc-0-20-0, fuel-core-0-18-0-nightly-2023-04-29) by collecting, filtering (filters.nix) and patching (patches.nix) all manifests. Also provide package sets for the latest semver releases and nightlies e.g. (fuel-latest, fuel-nightly).
3. Provide a special set of "milestone" packages (e.g. forc-wallet-testnet) and package sets (e.g. fuel-testnet) by finding packages that match the commits specified in milestones.nix.
4. Provide devShells to assist working on the fuel repos by collecting all of the inputs to their associated packages and inheriting their environment variables.

Click on the links above to dive into more details on each step.

Alternatively, for a quick look at adding or updating packages:

• Adding Packages
• Updating Packages
• Updating Flake Inputs

Generating Manifests

In fuel.nix, "Manifests" are small nix files that declare some unique properties for a particular version of a particular package. These manifests are used by flake.nix to provide all of the fuel packages in a declarative, reproducible manner.

Here's an example of what a manifest looks like:

{
  pname = "fuel-core";
  version = "0.18.0";
  date = "2023-04-27";
  url = "https://github.com/fuellabs/fuel-core";
  rev = "19f12eab187928cf15289193c710f63417343d33";
  sha256 = "sha256-FD9GbSxPhXAWrl40I9lzmEHQ4R2FD3ECYKmipfRPhlU=";
}

Refreshing Manifests on CI

Each night at 00:00 UTC, the fuel.nix repo's refresh-manifests GitHub action runs the ./scripts/refresh-manifests.sh script.

The role of this script is to fetch each of the FuelLabs GitHub repositories, scan them for all versioned releases (by checking their git tags) and for all nightly releases (by checking timestamps) in order to generate a unique manifest for every version of every package and store them under the ./manifests/ directory.

The GitHub action checks the diff to see if there are any new manifests since the previous night. If so, it attempts to build and cache them on each supported platform. Upon success, the action commits the new manifests directly to the master branch.

Refreshing Manifests Locally

As a maintainer, you can run the script locally by cloning the repository, cding into the repo and running:

nix run .#refresh-manifests

Running the script like this will ensure you have access to the necessary tools. These include git, coreutils (for the date cmd), nix (used to generate the package src sha256 hashes) and semver-tool (used to validate the semver retrieved from git tags).

After running the script, you can use git status to see if any new manifests have been generated. You can commit and open a PR with these changes at any time, or simply wait for the next nightly refresh-manifests GitHub action to run.

Notes on ./scripts/refresh-manifests.sh

The script begins by declaring all FuelLabs repositories that we care about, followed by each unique package and which repository it is associated with. To declare new packages, see the Adding Packages chapter.

The script aims to be idempotent, i.e. even if you were to delete the entire ./manifests directory and all its manifests, running the script again should reproduce the exact same directory with the same set of manifests, assuming the git history of each of the FuelLabs repos was not edited in some manner.

Running the script can take a long time. This is because we scan each repository in its entirety multiple times - once while generating nightly manifests, and again while generating semver release manifests.

Providing Packages

fuel.nix provides packages as Nix flake package outputs.

Overview

The way in which fuel.nix creates package outputs is as follows:

1. Load all manifests from the ./manifests/ directory (see Generating Manifests).
2. Filter out manifests for package versions that are known to be broken, or untested versions that are older than fuel.nix itself, by applying the list of conditions in ./filters.nix.
3. Patch the remaining manifests with their necessary build inputs (e.g. openssl, rust, etc) and environment variables based on the list of patches in ./patches.nix.
4. Split manifests into published (e.g. forc-0-28-0) and nightly (e.g. fuel-core-0-18-0-nightly-2023-05-04) sets based on their file suffix.
5. Pass the resulting sets of manifests to mkPackages and use the buildRustPackage function to build a unique package for each.
6. Create special packages for each package set using symlinkJoin, e.g. fuel-latest (aliased to fuel) and fuel-nightly.

The following shares some more details on each stage.

Filtering Manifests

After loading all manifests into a list by reading them from the ./manifests/ directory, we first apply the filters to cull versions that are known to be broken or that are too old.

Filters are a list of conditions loaded from the ./filters.nix file. Only manifests that satisfy all of these conditions will be used to provide packages.

Conditions are functions where given a manifest m, return whether or not the manifest should be included.

The following is an example of one of the conditions in ./filters.nix:

  (m: m.pname != "forc" || versionAtLeast m.version "0.19.0")

This condition implies that only forc versions that are at least 0.19.0 or greater will be included. This means nix build .#forc-0-19-0 should work, though nix build .#forc-0-17-0 will not.

Patching Manifests

After filtering out unnecessary or known-broken manifests, we build up the remaining manifests by applying the list of patches loaded from ./patches.nix.

Each patch includes:

1. A condition that must be met for the patch to be applied and
2. A patch function that provides the extra attributes that should be merged into the existing manifest.

All patches are applied to all manifests in the order in which they are declared in the patches.nix list, provided that they meet the patch's condition.

Using Patches to Fix Manifests

The following is an example taken from patches.nix that applies a fix for a known broken forc-wallet version:

  # A patch for some `forc-wallet` nightlies whose committed `Cargo.lock` file
  # was out of date.
  {
    condition = m: m.pname == "forc-wallet" && m.version == "0.1.0" && m.date < "2022-09-04";
    patch = m: {
      cargoPatches = [
        ./patch/forc-wallet-0.1.0-update-lock.patch
      ];
      cargoHash = "sha256-LXQaPcpf/n1RRFTQXAP6PexfEI67U2Z5OOW5DzNJvX8=";
      cargoLock = null;
    };
  }

As the condition suggests, the patch is only applied to forc-wallet manifests with a version equal to 0.1.0 and whose commit date precedes 2022-09-04.

Using Patches to Extend Manifests

Patches are not only used to fix existing manifests, but also to build up commonly required attributes in a simple manner. For example, the following patch is the first patch in the list:

  # By default, most packages have their `Cargo.lock` file in the repo root.
  # We also specify a base, minimum Rust version. This version should never
  # change in order to avoid invalidating the cache for all previously built
  # packages. Instead, if a new version of a fuel package requires a newer
  # version of Rust, we should specify the necessary condition in a new patch
  # to ensure only newer packages use the newer version of Rust.
  {
    condition = m: true;
    patch = m: {
      cargoLock.lockFile = "${m.src}/Cargo.lock";
      meta.homepage = m.src.gitRepoUrl;
      rust = pkgs.rust-bin.stable."1.63.0".default;
    };
  }

As the condition implies, this patch is currently applied to all manifests. The patch function provides some commonly useful attributes for building Rust packages, i.e. the common location for the lock file, the default version of Rust, and some package metadata about where the repository is located.

Note: This condition may need to be changed in the future when aiming to support distributing non-Rust Fuel projects from fuel.nix.

Adding or Changing Patches

In general, it is better to add new patches with conditions that only apply to newer packages when accounting for newly introduced dependencies or changes to a package's build environment.

This approach ensures we don't accidentally break older versions of packages, and allows us to isolate each change clearly with its own entry in the list.

Here's a patch that was added to account for an update in the Rust version used:

  # `fuel-core` needs Rust 1.64 as of bcb86da09b6fdce09f13ef4181a0ca6461f8e2a8.
  # This changes the Rust used for all pkgs to 1.64 from the day of the commit.
  {
    condition = m: m.date >= "2022-09-23";
    patch = m: {
      rust = pkgs.rust-bin.stable."1.64.0".default;
    };
  }

It avoids breaking older versions by only applying the patch to manifests whose commits after dated after 2022-09-23.

Overriding Attributes

The example above also demonstrates how attributes can be overridden. In the previous patch example above, the rust attribute was set to version 1.63.0, however the patch above overrides this attribute for all manifests created on or after 2023-09-23, setting the version to 1.64.0.

Multiple Rust version changes can be found throughout patches.nix that override the version following a particular date.

Building Packages

Now that we have our final sets of manifests, we can build our flake's package outputs from them.

This involves mapping the manifests we constructed with the buildRustPackage function provided by the Rust platform. This is all performed within the flake's mkPackages function.

Package outputs are created for the published and nightly releases of each individual package (e.g. forc-0-28-0, fuel-core-0-18-0-nightly-2023-05-04).

Note: The use of hyphens for delineating semver versions rather than periods! This can be a common gotcha when trying to use packages. E.g. nix run .#forc-0.18.0 is invalid, but nix run .#forc-0-18-0 is valid.

Package Sets

Unique packages are also created for each of the common package sets. These can be thought of as packages that provide multiple other packges at once.

Most notably, we provide:

• fuel (aliased from fuel-latest) - Provides the latest semver version of every Fuel tool.
• fuel-nightly - Provides the latest nightly version of every Fuel tool.

Sets are also provided for each milestone, however this is covered in the Providing Milestones chapter.

Other Packages

While mkPackages mostly focuses on generating package outputs for all of Fuel's Rust packages, it also provides a couple of "hand-written" packages:

1. refresh-manifests - This is a small package for the script used to refresh the manifests under the ./manifests/ directory.
2. sway-vim - A Vim plugin derivation for NixOS or Nix home-manager users who want to configure Vim in their Nix configuration.

Providing Milestones

fuel.nix allows for declaring "milestones".

Milestones provide a way of pinning a significant set of hand-picked commits across the Fuel ecosystem under a single named release.

Milestones are provided by the ./milestones.nix file.

Each milestone is a mapping from a name to a set of repository commits, each of which is used to select the set of package manifests used to generate package outputs for the milestone.

Here's what the beta-2 milestone looks like:

  beta-2 = {
    forc-explorer = "4bb7392eed085ee3a6795b98ea25392b3f41ade8";
    forc-wallet = "9473052e88048f58e8c4e1eba0ff88ef6a4cdd59";
    fuel-core = "49e4305fea691bbf293c606334e7b282a54393b3";
    fuel-indexer = "c2425c8b63f01ef1b540ff3e5832ebdc018b951d";
    sway = "c32b0759d25c0b515cbf535f9fb9b8e6fda38ff2";
  };

While providing packages, milestones are used to provide a unique output for each package along with a dedicated package set. E.g. the above beta-2 milestone is used to provide fuel-core-beta-2 and forc-beta-2 package aliases, as well as the extra fuel-beta-2 package set.

Adding milestones

Choosing Commits

When selecting commits from each repository for a new milestone, it can be a good idea to do so from the top-down. I.e. First select a commit for the Sway repo, then select commits for repos with dependencies (e.g. fuel-core) by checking the versions that are tested under the Sway commit's integration testing.

CI

To ensure we maintain availability of milestone binaries in the cache, we build each of the milestones under the CI workflow.

Currently, the milestones are manually specified. As a result, they'll need to be updated upon adding new milestones, or removed when they're no longer officially supported.

Adding Packages

Adding new packages requires making small updates to multiple sections of fuel.nix:

Updating ./scripts/refresh-manifests.sh

If the new package requires adding a new repository, first add an entry to the set of repositories:

# The set of fuel repositories.
declare -A fuel_repos=(
    [forc-wallet]="https://github.com/fuellabs/forc-wallet"
    [fuel-core]="https://github.com/fuellabs/fuel-core"
    [sway]="https://github.com/fuellabs/sway"
    [sway-vim]="https://github.com/fuellabs/sway.vim"
)

Next, add a dedicated package declaration:

# The set of packages.
declare -A pkg_forc=(
    [name]="forc"
    [repo]="${fuel_repos[sway]}"
)
declare -A pkg_forc_client=(
    [name]="forc-client"
    [repo]="${fuel_repos[sway]}"
)
declare -A pkg_forc_doc=(
    [name]="forc-doc"
    [repo]="${fuel_repos[sway]}"
)
# ...

Finally, add a call to refresh for the new package:

refresh pkg_forc
refresh pkg_forc_client
refresh pkg_forc_doc
refresh pkg_forc_fmt
refresh pkg_forc_index
refresh pkg_forc_lsp
refresh pkg_forc_tx
refresh pkg_forc_wallet
refresh pkg_fuel_core
refresh pkg_fuel_core_client
refresh pkg_fuel_indexer

This should ensure that the new package's manifests are generated as a part of the nightly refresh-manifests CI action.

Updating ./filters.nix

It's often useful to filter out older versions that will never be tested by the flake's CI.

We can do so by adding a condition to the list of filters:

  (m: m.pname != "forc" || versionAtLeast m.version "0.19.0")
  (m: m.pname != "forc-client" || versionAtLeast m.version "0.19.0")
  # ...

See the Filtering Manifests section for more details.

Updating ./patches.nix

If necessary, add a custom patch for the new package including any necessary unique attributes, environment variables, etc:

    {
      condition = m: m.pname == "forc-client";
      patch = m: {
        buildAndTestSubdir = "forc-plugins/${m.pname}";
        nativeBuildInputs = [
          pkgs.perl # for openssl-sys
          pkgs.pkg-config # for openssl-sys
        ];
      };
    }

For more details on how to apply manifest patches, see the Patching Manifests section.

Tip: Check the new package's upstream CI to get an idea of what system dependencies, build inputs and environment setup might be required for the patch.

Updating ./milestones.nix

If the new package is provided from a new repository, ensure the new repository is added to the milestones as necessary.

Package Sets

The new package should automatically be included as a part of the fuel, fuel-nightly and milestone package sets.

Example Commits

The following commits show the basics of adding a new package. In this case, the forc-client plugin.

• Add forc-client to the refresh-manifests script
• Add forc-client package to the nix flake

Updating Packages

Every now and then, a new nightly or published version of an upstream package may add some new dependency or build environment requirement.

In order to avoid breaking older packages or invalidating the cache for existing versions, we can make the necessary changes for new versions by adding a new patch to ./patches.nix.

See the Patching Manifests section for details.

Updating Flake Inputs

Nix flakes can be thought of as a collection of pure functions that produce a plan for how to provide packages, devShells and other outputs.

Any external inputs to these functions must be declared as a part of the flake inputs. Apart from these, only files available within the flake's repository (or fetchers that can verify reproducibility of the fetched content using a hash) may be used to construct flake outputs.

Here's what fuel.nix's flake inputs look like today:

  inputs = {
    nixpkgs = {
      url = "github:NixOS/nixpkgs/nixos-unstable";
    };
    rust-overlay = {
      url = "github:oxalica/rust-overlay/master";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    sway-vim-src = {
      url = "github:fuellabs/sway.vim";
      flake = false;
    };
    utils = {
      url = "github:numtide/flake-utils";
    };
  };

Our inputs include:

• nixpkgs - The main nix package repository, providing most packages you could imagine.
• rust-overlay - A nixpkgs overlay for providing more fine-grained control over selecting Rust versions, choosing components, etc. It can be thought of as a nix-esque version of rustup.
• sway-vim-src - Unlike the other fuel packages, we only provide the latest version of the sway-vim plugin. This input provides the repo for the plugin.
• utils - Some flake utility functions that make it a little easier to provide outputs for multiple different systems.

Updating Inputs

Inputs are locked to a set of commits via the flake.lock file. Occasionally it might be necessary to update nixpkgs or rust-overlay in order to get access to some new version of Rust, a new openssl version with a security patch, etc.

To update all inputs:

nix flake update

To update a single input:

nix flake lock --update-input nixpkgs

After updating, be sure to commit the changes to the lock file (CI should fail if you forget). It's best to update inputs in a dedicated PR, as doing so may have implications on the way package's are built.

Cache Implications

It's worth keeping in mind that updating inputs will result in new derivations for existing packages in the case that existing packages use something provided by the updated input that might have changed. As a result, it's better to update nixpkgs only as necessary.

A possible future solution to this might be to update nixpkgs versions in the same way that we update Rust versions, i.e. using patches.nix. This may require a bit of a refactor of patches.nix (e.g. fetch nixpkgs at pinned commits internally using fetchFromGitHub, rather than passing in pkgs as an input), and would likely still require at least one version of nixpkgs as an input in order to provide useful nix functions via lib outside of the package outputs.