Rust: Difference between revisions
imported>Malteneuss m Add another external library example with sqlite for database tool diesel, and refer to other FAQ page why it has to be a nix-shell environment |
Phanirithvij (talk | contribs) m dream2nix update link |
||
(52 intermediate revisions by 32 users not shown) | |||
Line 1: | Line 1: | ||
This article is about the [https://www.rust-lang.org Rust programming language]. There are 3 methods to use the | This article is about the [https://www.rust-lang.org Rust programming language]. There are 3 methods to use the Rust compiler and toolchain in Nix/NixOS: | ||
# via nixpkgs, | # via nixpkgs, | ||
Line 5: | Line 5: | ||
# or with unofficial overlays on nixpkgs. | # or with unofficial overlays on nixpkgs. | ||
Installing via nixpkgs is the | Installing via nixpkgs is the best way to use Rust, but there are valid reasons to use any approach. | ||
== Installing via nixpkgs == | == Installing via nixpkgs == | ||
The <code>cargo</code> and <code>rustc</code> derivations provide the | The <code>cargo</code> and <code>rustc</code> derivations provide the Rust toolchain in nixpkgs. An advantage of using nixpkgs is that it's dead simple and you get pinned versions, deterministic builds in nix-shell, etc. However, nixpkgs only maintains a single version of the Rust stable toolchain, so if you require a nightly toolchain or switch between multiple toolchains then this approach may not be for you. | ||
Here's an example <code>shell.nix</code>: | Here's an example <code>shell.nix</code>: | ||
Line 24: | Line 24: | ||
</syntaxHighlight> | </syntaxHighlight> | ||
== | == Installating with bindgen support == | ||
By default crates using <code>bindgen</code> will not compile. To add bindegen support add the <code>rustPlatform.bindegenHook</code> to your <code>nativeBuildInputs</code>. | |||
Here's an example <code>shell.nix</code>: | |||
<syntaxHighlight lang="nix"> | <syntaxHighlight lang="nix"> | ||
{ pkgs ? import <nixpkgs> {} }: | |||
pkgs.mkShell { | |||
nativeBuildInputs = [ | |||
pkgs.cargo | |||
pkgs.cargo | |||
pkgs.rustc | pkgs.rustc | ||
pkgs. | pkgs.rustPlatform.bindgenHook | ||
# optional: add pkg-config support | |||
pkgs.pkg-config | |||
]; | ]; | ||
buildInputs = [ | |||
# add desired native packages | |||
# ... | |||
]; | |||
# ... | |||
} | |||
</syntaxHighlight> | |||
This also works, when compiling rust crates: | |||
<syntaxHighlight lang="nix"> | |||
{ | |||
rustPlatform, | |||
pkg-config, | |||
... | |||
}: | |||
rustPlatform.buildRustPackage { | |||
# ... | |||
nativeBuildInputs = [ | |||
rustPlatform.bindgenHook | |||
pkg-config | |||
]; | |||
buildInputs = [ | |||
# add desired native packages | |||
# ... | |||
]; | |||
} | } | ||
</syntaxHighlight> | </syntaxHighlight> | ||
== Installation via rustup == | == Installation via rustup == | ||
The rustup tool is maintained by the | The rustup tool is maintained by the Rust community and offers an interface to install and switch between Rust toolchains. In this scenario, rustup handles the "package management" of Rust toolchains and places them in <code>$PATH</code>. Nixpkgs offers rustup via the <code>rustup</code> derivation. More info on using rustup can be found on their official website: https://rustup.rs/. | ||
If you want | If you want the most "normal" Rust experience I recommend using rustup with the following example shell.nix: | ||
<syntaxHighlight lang="nix"> | <syntaxHighlight lang="nix"> | ||
{ pkgs ? import <nixpkgs> {} }: | { pkgs ? import <nixpkgs> {} }: | ||
let | |||
overrides = (builtins.fromTOML (builtins.readFile ./rust-toolchain.toml)); | |||
libPath = with pkgs; lib.makeLibraryPath [ | |||
# load external libraries that you need in your rust project here | |||
]; | |||
in | |||
pkgs.mkShell rec { | pkgs.mkShell rec { | ||
buildInputs = with pkgs; [ | buildInputs = with pkgs; [ | ||
clang | |||
# Replace llvmPackages with llvmPackages_X, where X is the latest LLVM version (at the time of writing, 16) | |||
llvmPackages.bintools | |||
rustup | rustup | ||
]; | ]; | ||
RUSTC_VERSION = | RUSTC_VERSION = overrides.toolchain.channel; | ||
# https://github.com/rust-lang/rust-bindgen#environment-variables | # https://github.com/rust-lang/rust-bindgen#environment-variables | ||
LIBCLANG_PATH= pkgs.lib.makeLibraryPath [ pkgs.llvmPackages_latest.libclang.lib ] | LIBCLANG_PATH = pkgs.lib.makeLibraryPath [ pkgs.llvmPackages_latest.libclang.lib ]; | ||
shellHook = '' | shellHook = '' | ||
export PATH=$PATH:~/.cargo/bin | export PATH=$PATH:''${CARGO_HOME:-~/.cargo}/bin | ||
export PATH=$PATH:~/.rustup/toolchains/$RUSTC_VERSION-x86_64-unknown-linux-gnu/bin/ | export PATH=$PATH:''${RUSTUP_HOME:-~/.rustup}/toolchains/$RUSTC_VERSION-x86_64-unknown-linux-gnu/bin/ | ||
''; | ''; | ||
# Add | # Add precompiled library to rustc search path | ||
RUSTFLAGS = (builtins.map (a: ''-L ${a}/lib'') [ | RUSTFLAGS = (builtins.map (a: ''-L ${a}/lib'') [ | ||
pkgs.libvmi | # add libraries here (e.g. pkgs.libvmi) | ||
]); | ]); | ||
# Add | LD_LIBRARY_PATH = libPath; | ||
BINDGEN_EXTRA_CLANG_ARGS = | # Add glibc, clang, glib, and other headers to bindgen search path | ||
# Includes | BINDGEN_EXTRA_CLANG_ARGS = | ||
# Includes normal include path | |||
(builtins.map (a: ''-I"${a}/include"'') [ | (builtins.map (a: ''-I"${a}/include"'') [ | ||
pkgs.libvmi | # add dev libraries here (e.g. pkgs.libvmi.dev) | ||
pkgs.glibc.dev | pkgs.glibc.dev | ||
]) | ]) | ||
# Includes with special directory paths | # Includes with special directory paths | ||
Line 92: | Line 112: | ||
''-I${pkgs.glib.out}/lib/glib-2.0/include/'' | ''-I${pkgs.glib.out}/lib/glib-2.0/include/'' | ||
]; | ]; | ||
} | } | ||
</syntaxHighlight> | </syntaxHighlight> | ||
It's important to have a file named <code>rust-toolchain</code> lying in the same directory as the shell.nix. | It's important to have a file named <code>rust-toolchain.toml</code> lying in the same directory as the shell.nix. | ||
Rust already has a standardized way of pinning a toolchain version for a workspace or a project. | |||
< | See [https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file the Rustup book] for its syntax. | ||
nightly- | A minimal example of the <code>rust-toolchain.toml</code>: | ||
</ | <syntaxhighlight lang="toml"> | ||
[toolchain] | |||
channel = "stable" # This can also be "nightly" if you want a nightly rust | |||
# or nightly-20XX-XX-XX for a specific nightly. | |||
</syntaxhighlight> | |||
The | The important part is that this also works with complex setups using bindgen and precompiled C libraries. To add a new C library in the search path of bindgen and rustc edit the variables <code>BINDGEN_EXTRA_CLANG_ARGS</code> and <code>RUSTFLAGS</code> | ||
== Cross-compiling == | == Cross-compiling == | ||
=== To | === To Windows via rustup === | ||
* [https://github.com/jraygauthier/jrg-rust-cross-experiment/tree/master/simple-static-rustup-target-windows simple-static-rustup-target-windows] | * [https://github.com/jraygauthier/jrg-rust-cross-experiment/tree/master/simple-static-rustup-target-windows simple-static-rustup-target-windows] | ||
Line 116: | Line 139: | ||
# https://github.com/oxalica/rust-overlay (Flake support, Nightly & Stable) | # https://github.com/oxalica/rust-overlay (Flake support, Nightly & Stable) | ||
# https://github.com/nix-community/fenix (Flake support, Nightly & Stable) | # https://github.com/nix-community/fenix (Flake support, Nightly & Stable) | ||
# https://github.com/mozilla/nixpkgs-mozilla (Nightly & Stable) | # https://github.com/mozilla/nixpkgs-mozilla (Flake support, Nightly & Stable) | ||
== | == devenv.sh support == | ||
# | # https://github.com/cachix/devenv/blob/main/examples/rust/devenv.nix and <code>devenv shell</code> | ||
== Developing Rust projects using Nix == | == Developing Rust projects using Nix == | ||
The [https://nixos.org/manual/nixpkgs/stable/#rust Nixpkgs manual] uses <code>buildRustPackage</code>. | |||
[https://srid.ca/rust-nix This] blog post shows how to do it using <code>dream2nix</code>. A template repo is available here: https://github.com/srid/rust-nix-template | |||
== Using overrideAttrs with Rust Packages == | |||
[https://discourse.nixos.org/t/is-it-possible-to-override-cargosha256-in-buildrustpackage/4393/7 This does not seem to be possible.] | |||
== Using overrideArgs with Rust Packages == | |||
This is a bit tricky, you can't just use <code>overrideArgs</code>. [https://discourse.nixos.org/t/is-it-possible-to-override-cargosha256-in-buildrustpackage/4393/3 Here] is one example of how to do it. The trick is to use two nested calls to <code>overrideAttrs</code>; the outer call overrides the <code>cargoDeps</code> attribute, the inner call rebuilds the vendored tarball and provides the updated hash: | |||
<syntaxHighlight lang="nix"> | <syntaxHighlight lang="nix"> | ||
overlays = [ | |||
(final: prev: { | |||
some-nixpkgs-package = prev.some-nixpkgs-package.overrideAttrs (oldAttrs: { | |||
cargoDeps = oldAttrs.cargoDeps.overrideAttrs (_: { | |||
# ... | |||
}); | |||
}); | |||
}) | |||
]; | |||
} | |||
</syntaxHighlight> | </syntaxHighlight> | ||
== Packaging Rust projects with nix == | == Packaging Rust projects with nix == | ||
At the time of writing, there are now no less than | At the time of writing, there are now no less than 8 different solutions for building Rust code with Nix. In the following table they are compared: | ||
{| | {| | ||
Line 171: | Line 189: | ||
| Yes | | Yes | ||
| Built into nixpkgs | | Built into nixpkgs | ||
|- | |- | ||
| [https://github.com/kolloch/crate2nix <code>crate2nix</code>] | | [https://github.com/kolloch/crate2nix <code>crate2nix</code>] | ||
Line 183: | Line 194: | ||
| Many | | Many | ||
| <code>buildRustCrate</code> | | <code>buildRustCrate</code> | ||
| | | [https://github.com/kolloch/crate2nix/commit/8bfeb42bda097e0bdf5452691a5e157aad3cc11f experimental] | ||
| Spiritual successor to | | Spiritual successor to [https://github.com/nix-community/carnix <code>carnix</code>] | ||
|- | |- | ||
| [https://github.com/nmattia/naersk/ <code>naersk</code>] | | [https://github.com/nmattia/naersk/ <code>naersk</code>] | ||
Line 190: | Line 201: | ||
| 2 | | 2 | ||
| cargo | | cargo | ||
| | | Yes | ||
| [https://github.com/nmattia/naersk/blob/22b96210b2433228d42bce460f3befbdcfde7520/rust/rustc.nix#L22-L29 Seems to only support building on x86] | | [https://github.com/nmattia/naersk/blob/22b96210b2433228d42bce460f3befbdcfde7520/rust/rustc.nix#L22-L29 Seems to only support building on x86] | ||
|- | |- | ||
Line 196: | Line 207: | ||
| Codegen | | Codegen | ||
| Many | | Many | ||
| | | cargo + custom | ||
| Yes | | Yes | ||
| | | Defaults to the oxalica Rust overlay but this can be overridden with <code>rustToolchain</code> | ||
|- | |- | ||
| [https://github.com/edolstra/import-cargo <code>import-cargo</code>] | | [https://github.com/edolstra/import-cargo <code>import-cargo</code>] | ||
Line 206: | Line 217: | ||
| Unclear | | Unclear | ||
| More of a proof of concept than a full working solution | | More of a proof of concept than a full working solution | ||
|- | |||
| [https://github.com/ipetkov/crane <code>crane</code>] | |||
| Import | |||
| 2 | |||
| cargo | |||
| [https://github.com/ipetkov/crane/tree/master/examples Yes] | |||
| Inspired by naersk, with [https://discourse.nixos.org/t/introducing-crane-composable-and-cacheable-builds-with-cargo/17275/4 better support for composing Cargo invocations as completely separate derivations] | |||
|- | |||
| [https://dream2nix.dev/reference/rust-crane <code>dream2nix</code>] | |||
| Codegen | |||
| 1 or 2 | |||
| cargo (via <code>buildRustPackage</code> or <code>crane</code>) | |||
| Yes | |||
| A framework for unifying 2nix converters across languages (Experimental) | |||
|} | |} | ||
Line 211: | Line 236: | ||
* '''Cargo.lock solution:''' How does this solution handle reproducibly determining what crates need to be downloaded from the Cargo.lock file? “Checksum” means it requires you to specify the checksum of all the downloaded dependencies. “Import” means it dynamically imports and parses Cargo.lock from a Nix expression, which means Cargo.lock needs to be present in the same repository as the nix expressions (or IFD must be used). “Codegen” means it generates a .nix file from the Cargo.lock, which is then committed to source control. | * '''Cargo.lock solution:''' How does this solution handle reproducibly determining what crates need to be downloaded from the Cargo.lock file? “Checksum” means it requires you to specify the checksum of all the downloaded dependencies. “Import” means it dynamically imports and parses Cargo.lock from a Nix expression, which means Cargo.lock needs to be present in the same repository as the nix expressions (or IFD must be used). “Codegen” means it generates a .nix file from the Cargo.lock, which is then committed to source control. | ||
* '''Derivations:''' How many derivations does this solution use to compile | * '''Derivations:''' How many derivations does this solution use to compile Rust code? “1” means the project and all its dependencies are compiled in one derivation. “2” means all dependencies are moved into a separate derivation, so the project can be updated independently, but any change to the set of dependencies rebuilds everything. “Many” means each dependency is built in its own derivation, so changes to dependencies only do the minimal amount of rebuilding necessary (and, ideally, different projects can share dependencies, although I haven’t checked if this works in practice). | ||
* '''Build logic:''' How does this solution orchestrate building of crates? “Cargo” means it relies on Cargo; <code>buildRustCrate</code> means it uses Nixpkgs’ <code>buildRustCrate</code>; “custom” means it uses its own custom logic | * '''Build logic:''' How does this solution orchestrate building of crates? “Cargo” means it relies on Cargo; <code>buildRustCrate</code> means it uses Nixpkgs’ <code>buildRustCrate</code>; “custom” means it uses its own custom logic. <code>buildRustPackage</code> means it uses Nixpkgs' <code>buildRustPackage</code>, which in turn uses Cargo. | ||
* '''Supports cross:''' Does the solution allow for cross-compilation of crates? | * '''Supports cross:''' Does the solution allow for cross-compilation of crates? | ||
Line 219: | Line 244: | ||
{ pkgs ? import <nixpkgs> {} }: | { pkgs ? import <nixpkgs> {} }: | ||
pkgs.mkShell { | pkgs.mkShell { | ||
nativeBuildInputs = with pkgs; [ rustc cargo gcc | nativeBuildInputs = with pkgs; [ rustc cargo gcc rustfmt clippy ]; | ||
# Certain Rust tools won't work without this | |||
# This can also be fixed by using oxalica/rust-overlay and specifying the rust-src extension | |||
# See https://discourse.nixos.org/t/rust-src-not-found-and-other-misadventures-of-developing-rust-on-nixos/11570/3?u=samuela. for more details. | |||
RUST_SRC_PATH = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; | RUST_SRC_PATH = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; | ||
} | } | ||
</syntaxHighlight> | </syntaxHighlight> | ||
This will have the stable | This will have the stable Rust compiler + the official formatter and linter inside the ephemeral shell. It'll also set the RUST_SRC_PATH environment variable to point to the right location, which tools, such as rust-analyzer, require to be set. | ||
=== Custom Rust version === | |||
<syntaxHighlight lang="nix"> | |||
/* | |||
based on | |||
https://discourse.nixos.org/t/how-can-i-set-up-my-rust-programming-environment/4501/9 | |||
*/ | |||
let | |||
rust_overlay = import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"); | |||
pkgs = import <nixpkgs> { overlays = [ rust_overlay ]; }; | |||
rustVersion = "latest"; | |||
#rustVersion = "1.62.0"; | |||
rust = pkgs.rust-bin.stable.${rustVersion}.default.override { | |||
extensions = [ | |||
"rust-src" # for rust-analyzer | |||
"rust-analyzer" | |||
]; | |||
}; | |||
in | |||
pkgs.mkShell { | |||
buildInputs = [ | |||
rust | |||
] ++ (with pkgs; [ | |||
pkg-config | |||
# other dependencies | |||
#gtk3 | |||
#wrapGAppsHook | |||
]); | |||
RUST_BACKTRACE = 1; | |||
} | |||
</syntaxHighlight> | |||
=== VSCode integration === | |||
The [https://marketplace.visualstudio.com/items?itemName=rust-lang.rust rust-lang.rust] and [https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer rust-lang.rust-analyzer] VSCode extensions offer Rust support. | |||
You can use the [https://marketplace.visualstudio.com/items?itemName=arrterian.nix-env-selector arrterian.nix-env-selector] extension to enable your nix-shell inside VSCode and have these settings picked up by other extensions. | |||
== FAQ == | == FAQ == | ||
=== Building Rust crates that require external system libraries === | === Building Rust crates that require external system libraries === | ||
For example, the <code>openssl-sys</code> crate needs the OpenSSL static libraries and searches for the library path with <code>pkg-config</code>. That's why you need to have the Nix derivatives <code>openssl</code> and <code>pkg-config</code> in order to build that crate. You'll need to start a shell providing these packages: | For example, the <code>openssl-sys</code> crate needs the OpenSSL static libraries and searches for the library path with <code>pkg-config</code>. That's why you need to have the Nix derivatives <code>openssl</code> and <code>pkg-config</code> in order to build that crate. You'll need to start a shell providing these packages: | ||
<syntaxHighlight lang= | <syntaxHighlight lang="shell-session"> | ||
$ nix-shell -p pkg-config openssl | $ nix-shell -p pkg-config openssl | ||
</syntaxHighlight> | </syntaxHighlight> | ||
In some cases (eg [https://discourse.nixos.org/t/rust-openssl-woes/12340 here]) you may also need | In some cases (eg [https://discourse.nixos.org/t/rust-openssl-woes/12340 here]) you may also need | ||
<syntaxHighlight> | <syntaxHighlight lang="nix"> | ||
PKG_CONFIG_PATH = "${pkgs.openssl.dev}/lib/pkgconfig"; | PKG_CONFIG_PATH = "${pkgs.openssl.dev}/lib/pkgconfig"; | ||
</syntaxHighlight> | </syntaxHighlight> | ||
Similarly, the crate <code>libsqlite3-sys</code>, e.g. to use and compile the database ORM tool <code>diesel-cli</code> with Sqlite support, needs | Similarly, the crate <code>libsqlite3-sys</code>, e.g. to use and compile the database ORM tool <code>diesel-cli</code> with Sqlite support, needs | ||
<syntaxHighlight lang= | <syntaxHighlight lang="shell-session"> | ||
$ nix-shell -p pkg-config sqlite | $ nix-shell -p pkg-config sqlite | ||
</syntaxHighlight> | </syntaxHighlight> | ||
Otherwise the following error occurs: | Otherwise the following error occurs: | ||
<syntaxHighlight lang= | <syntaxHighlight lang="text"> | ||
error: linking with `cc` failed: exit status: 1 | error: linking with `cc` failed: exit status: 1 | ||
... | ... | ||
Line 250: | Line 314: | ||
</syntaxHighlight> | </syntaxHighlight> | ||
Note that you need to use a <code>nix-shell</code> environment. Installing the Nix packages <code>openssl</code> or <code>sqlite</code> globally under <code>systemPackages</code> in NixOS or in <code>nix-env</code> [ | Note that you need to use a <code>nix-shell</code> environment. Installing the Nix packages <code>openssl</code> or <code>sqlite</code> globally under <code>systemPackages</code> in NixOS or in <code>nix-env</code> [[FAQ/I installed a library but my compiler is not finding it. Why? | is discouraged]] and doesn't always work (<code>pkg-config</code> may not be able to locate the libraries). | ||
=== Building with a different Rust version than the one in Nixpkgs === | |||
The following uses the [https://github.com/nix-community/fenix fenix] overlay and <code>makeRustPlatform</code> to build a crate with Rust Nightly: | |||
<syntaxHighlight lang="nix"> | |||
{ | |||
inputs = { | |||
fenix = { | |||
url = "github:nix-community/fenix"; | |||
inputs.nixpkgs.follows = "nixpkgs"; | |||
}; | |||
flake-utils.url = "github:numtide/flake-utils"; | |||
nixpkgs.url = "nixpkgs/nixos-unstable"; | |||
}; | |||
outputs = { self, fenix, flake-utils, nixpkgs }: | |||
flake-utils.lib.eachDefaultSystem (system: | |||
let pkgs = nixpkgs.legacyPackages.${system}; in | |||
{ | |||
defaultPackage = (pkgs.makeRustPlatform { | |||
inherit (fenix.packages.${system}.minimal) cargo rustc; | |||
}).buildRustPackage { | |||
pname = "hello"; | |||
version = "0.1.0"; | |||
src = ./.; | |||
cargoSha256 = nixpkgs.lib.fakeSha256; | |||
}; | |||
}); | |||
} | |||
</syntaxHighlight> | |||
=== Using LLD instead of LD === | |||
If you want to use <code>lld</code>, then the correct way to do this is to use <code>pkgs.llvmPackages.bintools</code>, <em>not</em> <code>pkgs.lld</code>. This is because the former uses a wrapper script that correctly sets <code>rpath</code>. You can find more information about this [https://matklad.github.io/2022/03/14/rpath-or-why-lld-doesnt-work-on-nixos.html here]. | |||
[[Category:Languages]] |