DFINITY's cargo2nix fork. Original here.
Nixify your Rust projects today with cargo2nix
,
bringing you reproducible builds and better caching.
This repository hosts two components:
-
A Nixpkgs overlay, located at the
/overlay
directory, providing utilities to build and test your Cargo workspace. -
A utility written in Rust to generate version pins of crate dependencies.
Together, these components will take an existing Cargo.lock
and delegate the
process of fetching and compiling your dependencies (generated by Cargo) using
the deterministic Nix package manager.
This project assumes that the Nix package manager is
already installed on your machine. Run the command below to install cargo2nix
:
nix-env -iA package -f https://github.com/tenx-tech/cargo2nix/tarball/master
The basic process of converting an existing Cargo project to cargo2nix
boils
down to the following steps:
- Generate a
Cargo.nix
file by runningcargo2nix -f
at the root of your Cargo workspace. - Create a
default.nix
file which imports Nixpkgs with the cargo2nix and nixpkgs-mozilla overlays and builds your project using theCargo.nix
file from earlier. - Run
nix-build
to compile and/or test your project.
Check out our series of example projects which showcase how to use
cargo2nix
in detail.
You can optionally use any of these crate derivations as your nix-shell
development shell. The advantage of this shell is that in this environment users
can develop their crates and be sure that their crates builds in the same way
that cargo2nix
overlay will build them.
To do this, run nix-shell -A 'rustPkgs.<registry>.<crate>."x.y.z"' default.nix
.
For instance, the following command being invoked in this repository root drops
you into such a development shell.
# When a crate is not associated with any registry, such as when building locally,
# the registry is "unknown" as shown below.
nix-shell -A 'rustPkgs.unknown.cargo2nix."0.8.3"' default.nix
You will need to bootstrap some environment in this declarative development shell first.
runHook configureCargo # This overrides your .cargo folder, e.g. for setting cross-compilers
runHook setBuildEnv # This sets up linker flags for the `rustc` invocations
You will need to override your Cargo.toml
and Cargo.lock
in this shell,
so make sure that you have them backed up beforehand.
runHook overrideCargoManifest
Now you can use your favorite editor in this environment. To run the build
command used by cargo2nix
, use
runHook runCargo
-
Many
crates.io
public crates may not build using the current Rust compiler, unless a lint cap is put on these crates. For instance,cargo2nix
caps all lints towarn
by default. -
Nix 2.1.3 ships with a broken
builtins.fromTOML
function which is unable to parse lines of TOML that look like this:[target.'cfg(target_os = "linux")'.dependencies.rscam]
If Nix fails to parse your project's
Cargo.toml
manifest with an error similar to the one below, please upgrade to a newer version of Nix. Versions 2.3.1 and newer are not affected by this bug. If upgrading is not an option, removing the inner whitespace from the problematic keys should work around this issue.error: while parsing a TOML string at /nix/store/.../overlay/mkcrate.nix:31:14: Bare key 'cfg(target_os = "linux")' cannot contain whitespace at line 45
-
Git dependencies and crates from alternative Cargo registries rely on
builtins.fetchGit
to support fetching from private Git repositories. This means that such dependencies cannot be evaluated withrestrict-eval
applied.Also, if your Git dependency is tied to a Git branch, e.g.
master
, and you would like to force it to update on upstream changes, you should append--option tarball-ttl 0
to yournix-build
command.
This Nixpkgs overlay builds your Rust crates and binaries by first pulling the
dependencies apart, building them individually as separate Nix derivations and
linking them together. This is achieved by passing custom linker flags to the
cargo
invocations and the underlying rustc
and rustdoc
invocations.
In addition, this overlay takes cross-compilation into account and build the crates onto the correct host platform configurations with the correct platform-dependent feature flags specified in the Cargo manifests and build-time dependencies.
The design for the Nix overlay is inspired by the excellent work done by James Kay, which is described here and here. His source is available here. This work would have been impossible without these fantastic write-ups. Special thanks to James Kay!
cargo2nix
is free and open source software distributed under the terms of the
MIT License.