lastlog.de/blog
  • timeline
  • about
  • roadmap
  • websocket
  • drafts
  • special pages
  • login
prev. article next article
libnix

libnix - rust abstractions

11 apr 2025

nixlibnixcargorustcargo+libnix
  • libnix - rust abstractions
    • motivation
    • rust support in nixpkgs
      • using buildRustPackage
      • using buildRustCrate
      • summary of nixpkgs support
    • installing cargo/rustc toolchain(s)
    • drop-in replacements for buildRustPackage
      • experiments
    • drop-in replacements for buildRustPackage (obsolete)
    • summary

motivation

status quo of rust support in nixpkgs 24.05.20241104.d063c1d (Uakari)!

but first we recap how vanilla cargo workflow (no abstracted for nix) works:

  1. rustup installs the toolchain
  2. cargo build checks the Cargo.toml/Cargo.lock
  3. creates a target/ folder to work in
  4. creates a local crates.io registry copy in ~/.cargo/registry/
  5. builds all dependencies in target/debug/deps
  6. builds the program in target/debug/myprogram

the programmer has to take care of the target/ and ~/.cargo/ folder and there is no crates build artifacts sharing between different projects, let alone users.

rust support in nixpkgs

nixpkgs features:

  • one version of rust stable, 1.84, at time of writing
  • shipping 2159 rust applications using the buildRustPackage function from rustPlatform by wrapping cargo/rustc
  • a buildRustCrate implementation

this way nixpkgs supports 2159 rust applications, at time of this writing.

nixpkgs> git grep buildRustPackage *.nix | wc -l
2159

using buildRustPackage

buildRustPackage calls cargo which then calls rustc.

{ lib, stdenv, rustPlatform, fetchFromGitHub, pkg-config, openssl, libiconv,
  CoreServices, Security, SystemConfiguration
}:

rustPlatform.buildRustPackage rec {
  pname = "trunk";
  version = "0.21.1";

  src = fetchFromGitHub {
    owner = "trunk-rs";
    repo = "trunk";
    rev = "v${version}";
    sha256 = "sha256-6EuSz7bFlL49l5gjoKCyRTfAWiwIHFdG0t+StvGj7f8=";
  };

  nativeBuildInputs = [ pkg-config ];
  buildInputs = if stdenv.isDarwin
    then [ libiconv CoreServices Security SystemConfiguration]
    else [ openssl ];

  # requires network
  checkFlags = [ "--skip=tools::tests::download_and_install_binaries" ];

  cargoHash = "sha256-NfGDra5xHVY04CofTriCUspLY3f4Tiq6Wm9ON0K8jwY=";

  postConfigure = ''
    cargo metadata --offline
  '';

  meta = with lib; {
    homepage = "https://github.com/trunk-rs/trunk";
    description = "Build, bundle & ship your Rust WASM application to the web";
    maintainers = with maintainers; [ freezeboy flosse ];
    license = with licenses; [ asl20 ];
  };
}

when installing trunk, this abstraction:

  • creates a trunk-0.21.1-vendor.tar.gz with all the cargo libraries contained in this one file and
  • on each failing crate dependency it has to recompile all crate dependencies again.

using buildRustCrate

buildRustCrate replaces cargo and is used by crate2nix but not very much from nixpkgs itself.

See buildRustPackage implementation.

summary of nixpkgs support

the buildRustPackage, works remarkably well but there are many aspects where it lacks and motivates for projects like: crane, naersk, cargo2nix and crate2nix as well as drop-in toolchain replacements like oxalica/rust-overlay and fenix.

installing cargo/rustc toolchain(s)

this is like rustup: these projects bring rustc/cargo to your system so you can start developing ‘imperatively’ pretty similar to windows, linux and mac or you can use buildRustPackage!

# name stars toolchains commits open issues closed issues notes
1 nixpkgs ? stable ? ? ? nixpkgs built-in toolchain (using cargo),
built on hydra, also wraps cargo
2 oxalica/rust-overlay 830 stable, beta, nightly 1469 6 120 drop-in replacement to install different rust versions
3 fenix 620 stable, beta, nightly 1949 24 50 drop-in replacement to install different rust versions
4 nixpkgs-mozilla 511 ? 264 49 88 obsolete,
drop-in replacement to install different rust versions

Oxalica and fenix: 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).

Also worth mentioning:

  • oxalica / fenix does not compile any rustc or cargo binary but instead downloads pre-built executables from https://static.rust-lang.org
  • nixpkgs compiles rustc and cargo from source but notably also requires a binary download of these tools as a bootstrapping toolchain

drop-in replacements for buildRustPackage

crane naersk cargo2nix crate2nix
stars 819 677 407 338
tagged releases 52 0 14 10
commits 601 345 633 1336
open issues 21 50 62 80
closed issues 202 110 118 110
evaluator craneLib.mkDummySrc naersk.buildPackage rustBuilder.makePackageSet buildRustCrate (from nixpkgs)
store entry per crate download yes, 471 yes, 471 yes, 383 yes, 357
store entry per crate build no, one trunk-deps no, one trunk-deps yes, 384 yes, 358
custom registry support yes, download url, git index and sparse no, cratesDownloadUrl only replaces the crates.io url yes, git index, needs fetchCrateAlternativeRegistry passed to makePackageSet sparse only, only with a generated Cargo.nix (tools.nix rejects them)
IFD free yes, with a pure src,
registryFromGitIndex needs IFD
yes, with a pure src yes yes, with a generated Cargo.nix
also via IFD yes, if src comes from a derivation yes, if src comes from a derivation no built-in way yes, tools.nix
support tool no no cargo2nix creates Cargo.nix crate2nix creates Cargo.nix
builds trunk with cargo’s features yes, runs cargo yes, runs cargo yes, no fixes needed one crate override needed
uses lto and panic from [profile.release] yes, runs cargo yes, runs cargo yes, profile in Cargo.nix no
rustc which built trunk 1.82.0, from nixpkgs 1.82.0, from nixpkgs 1.82.0, from nixpkgs 1.82.0, from nixpkgs
default toolchain nixpkgs nixpkgs required in makePackageSet nixpkgs
change the toolchain overrideToolchain cargo and rustc arguments rustVersion, rustChannel, rustToolchain nixpkgs overlay for rustc
tests by default run off off off
trunk tests when enabled 77 passed, 1 skipped 77 passed, 1 skipped don’t compile 77 passed, 1 skipped
stale generated file nothing generated nothing generated stops with out of sync silently builds the old version
cross examples shipped musl, windows, rust-overlay windows, static musl, multi target 3-cross-compiling sample projects only
git dependencies from Cargo.lock, outputHashes optional from Cargo.lock from Cargo.lock, not with restrict-eval hash needed in crate-hashes.json
compiled crates shared between projects no no yes, if features match yes, if features match
rebuild after a comment in src/main.rs 1 crate(s)
291s
1 crate(s)
294s
1 crate(s)
288s
1 crate(s)
165s, no LTO
rebuild after a log update in Cargo.lock about 360 crate(s)
488s
about 360 crate(s)
403s
37 crate(s)
384s
38 crate(s)
289s, no LTO
rebuild after a comment in src/main.rs,
official rustc binary
1 crate(s)
169s
1 crate(s)
155s
1 crate(s)
179s
not measured
rebuild after a log update in Cargo.lock,
official rustc binary
about 360 crate(s)
286s
about 360 crate(s)
232s
37 crate(s)
236s
not measured

all four build trunk 0.21.4 with old pinned versions and the table describes that build on x86_64-linux. the custom registry, toolchain, cross and git dependency rows come from reading the sources, as does [profile.release] except for crate2nix, whose rustc call was checked in the build log. the others were measured.

  • store entries: crane and naersk download everything in Cargo.lock, cargo2nix and crate2nix only what the target and features need. the build counts include trunk itself. cargo2nix uses its own Cargo.lock here, so its numbers are not directly comparable
  • IFD: the crane and naersk flakes use fetchFromGitHub as src, so they need IFD as they are. with builtins.fetchTarball as src both evaluate without IFD
  • features: crate2nix turns nodejs = [ "dep:serde" ] from lightningcss into a serde feature, which cargo does not do. 20 of its 358 crates get such extra features, only lightningcss fails to build and needs the override
  • toolchain: all four compile trunk with rustc 1.82.0 from nixpkgs. in the crane, naersk and crate2nix flakes the rust-overlay/fenix toolchain is only used by the devShell. cargo2nix gets the nixpkgs compiler with rustToolchain and needs CARGO_NET_OFFLINE with it: cargo 1.82 re-resolves the single crate manifest cargo2nix generates and then asks for the crates.io index
  • sharing: a small project using itoa, log and serde in the versions from trunk shares only itoa with it, log and serde differ in features
  • rebuilds: these are single runs on one machine, so differences of about 10% mean little. crane’s tests are off to match the others and the official rustc rows ran in copies of the flakes. updating log rebuilds only the crates which depend on it: 37 of 384 with cargo2nix, 38 of 358 with crate2nix, while crane and naersk recompile all dependencies in trunk-deps, about 360 crates. still the per crate builds saved no time here: with the official rustc naersk needs 232s and cargo2nix 236s, because cargo compiles all dependencies in 74s while the 37 separate derivations take about 60s. crane is slower than naersk because buildDepsOnly runs cargo check and cargo build on all dependencies. compiling trunk itself takes most of the time in every rebuild and per crate builds can’t help there. cargo2nix uses its own Cargo.lock, so it updates log from 0.4.27 to 0.4.28 and the others from 0.4.22 to 0.4.26
  • compiler: the nixpkgs rustc and the official binary from https://static.rust-lang.org are the same version from the same commit, yet the official one is about 1.6 to 1.9 times faster here. the official builds use LTO, PGO and BOLT. PGO (profile-guided optimization) trains the compiler on real workloads and BOLT then reorders the machine code according to that profile. rustc.nix in nixpkgs sets none of these and links a shared LLVM from nixpkgs. it does not state why, but the likely reasons are that training means building the compiler several times, which is expensive for a package that gets rebuilt so often, and that a shared system LLVM is the normal way to package it for a distribution
  • LTO: normally rustc optimizes each crate on its own and the linker only joins the results. with link-time optimization the compiler optimizes the whole program at the final step, so it can inline and remove code across crates. trunk sets lto = "fat" in [profile.release], the strongest form, which merges everything into one unit: this gives a smaller and usually faster binary, but makes the final step slow and it runs after every change. crane, naersk and cargo2nix follow that setting. crate2nix does not, and it was not disabled there: it builds with buildRustCrate from nixpkgs, which calls rustc itself with opt-level and codegen-units only and never reads [profile.release], so panic = "abort" is lost as well. the sources give no reason, but the likely one is that LTO is a poor fit for this design: it works on the whole program, while buildRustCrate exists to build every crate on its own. this makes crate2nix the fastest here at 165s compared to about 290s, but its trunk is not the same build: 33.9 MB compared to 29.5 MB with crane

experiments

the experiments are at https://github.com/qknight/rust-nix-abstraction-tests

see:

  • crane
  • naersk
  • cargo2nix
  • crate2nix

to reproduce and play with the abstractions do:

  • clone the repo

    git clone https://github.com/qknight/rust-nix-abstraction-tests
  • list all related store activity:

    cd cargo2nix
    nix path-info --derivation --recursive .#default
  • hiearchically browse the store

    cd cargo2nix
    nix path-info --derivation --recursive .#default | grep trunk
    ... use the output to learn the exact store path ...
    nix-tree --derivation /nix/store/6ibmcbvb5wccaf2gpjpxlnhzja4r3qp0-trunk-0.21.4.drv

drop-in replacements for buildRustPackage (obsolete)

# name stars commits language notes
1 rust2nix 8 12 rust obsolete
2 carnix 10 43 pure nix obsolete,
3 nixcrates 15 63 rust obsolete, build crates (with custom cargo reimplementation written in rust),
lacks proper semver dependencies
4 cargo nix ? ? rust obsolete, given a crate name, downloads the latest version from crates.io & extracts it and pipes it through crate2nix and finally builds this with nix-build

summary

rust/cargo support in nix has come a long way and while there are over 2k rust-projects in nixpkgs, the nixpkgs abstraction is fairly limited and favours ease of deployment over a good developer experience.

  • tools like crane and naersk can be used like buildRustPackage.
  • cargo2nix and crate2nix try to replace later calls to cargo by creating a pure nix build system.

all in all, these abstractions require deep nix knowledge if something goes wrong and at times require lots of extra work from the developers and potentially lock-in into Nix and NixOS.

it sets the stage for a different concept: using nix directly from cargo. that will be the focus of the next article in the libnix series.

article source