Skip to content

Commit b373d29

Browse files
figsodafigsoda
committed
docs/rust: improve docs for nightly usage
1 parent 3b455ed commit b373d29

1 file changed

Lines changed: 76 additions & 96 deletions

File tree

‎doc/languages-frameworks/rust.section.md‎

Lines changed: 76 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ into your `configuration.nix` or bring them into scope with `nix-shell -p rustc
1313

1414
For other versions such as daily builds (beta and nightly),
1515
use either `rustup` from nixpkgs (which will manage the rust installation in your home directory),
16-
or use a community maintained [Rust overlay](#using-community-rust-overlays).
16+
or use [community maintained Rust toolchains](#using-community-maintained-rust-toolchains).
1717

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

@@ -686,148 +686,128 @@ $ cargo build
686686
$ cargo test
687687
```
688688

689-
### Controlling Rust Version Inside `nix-shell` {#controlling-rust-version-inside-nix-shell}
689+
## Using community maintained Rust toolchains {#using-community-maintained-rust-toolchains}
690690

691-
To control your rust version (i.e. use nightly) from within `shell.nix` (or
692-
other nix expressions) you can use the following `shell.nix`
691+
::: {.note}
692+
Note: The following projects cannot be used within nixpkgs since [IFD](#ssec-import-from-derivation) is disallowed.
693+
To package things that require Rust nightly, `RUSTC_BOOTSTRAP = true;` can sometimes be used as a hack.
694+
:::
695+
696+
There are two community maintained approaches to Rust toolchain management:
697+
- [oxalica's Rust overlay](https://github.com/oxalica/rust-overlay)
698+
- [fenix](https://github.com/nix-community/fenix)
699+
700+
Despite their names, both projects provides a similar set of packages and overlays under different APIs.
701+
702+
Oxalica's overlay allows you to select a particular Rust version without you providing a hash or a flake input,
703+
but comes with a larger git repository than fenix.
704+
705+
Fenix also provides rust-analyzer nightly in addition to the Rust toolchains.
706+
707+
Both oxalica's overlay and fenix better integrate with nix and cache optimizations.
708+
Because of this and ergonomics, either of those community projects
709+
should be preferred to the Mozilla's Rust overlay ([nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla)).
710+
711+
The following documentation demonstrates examples using fenix and oxalica's Rust overlay
712+
with `nix-shell` and building derivations. More advanced usages like flake usage
713+
are documented in their own repositories.
714+
715+
### Using Rust nightly with `nix-shell` {#using-rust-nightly-with-nix-shell}
716+
717+
Here is a simple `shell.nix` that provides Rust nightly (default profile) using fenix:
693718

694719
```nix
695-
# Latest Nightly
696-
with import <nixpkgs> {};
697-
let src = fetchFromGitHub {
698-
owner = "mozilla";
699-
repo = "nixpkgs-mozilla";
700-
# commit from: 2019-05-15
701-
rev = "9f35c4b09fd44a77227e79ff0c1b4b6a69dff533";
702-
hash = "sha256-18h0nvh55b5an4gmlgfbvwbyqj91bklf1zymis6lbdh75571qaz0=";
703-
};
720+
with import <nixpkgs> { };
721+
let
722+
fenix = callPackage
723+
(fetchFromGitHub {
724+
owner = "nix-community";
725+
repo = "fenix";
726+
# commit from: 2023-03-03
727+
rev = "e2ea04982b892263c4d939f1cc3bf60a9c4deaa1";
728+
hash = "sha256-AsOim1A8KKtMWIxG+lXh5Q4P2bhOZjoUhFWJ1EuZNNk=";
729+
})
730+
{ };
704731
in
705-
with import "${src.out}/rust-overlay.nix" pkgs pkgs;
706-
stdenv.mkDerivation {
732+
mkShell {
707733
name = "rust-env";
708-
buildInputs = [
709-
# Note: to use stable, just replace `nightly` with `stable`
710-
latest.rustChannels.nightly.rust
734+
nativeBuildInputs = [
735+
# Note: to use stable, just replace `default` with `stable`
736+
fenix.default.toolchain
711737
712-
# Add some extra dependencies from `pkgs`
713-
pkg-config openssl
738+
# Example Build-time Additional Dependencies
739+
pkg-config
740+
];
741+
buildInputs = [
742+
# Example Run-time Additional Dependencies
743+
openssl
714744
];
715745
716746
# Set Environment Variables
717747
RUST_BACKTRACE = 1;
718748
}
719749
```
720750

721-
Now run:
751+
Save this to `shell.nix`, then run:
722752

723753
```ShellSession
724754
$ rustc --version
725-
rustc 1.26.0-nightly (188e693b3 2018-03-26)
755+
rustc 1.69.0-nightly (13471d3b2 2023-03-02)
726756
```
727757

728758
To see that you are using nightly.
729759

730-
## Using community Rust overlays {#using-community-rust-overlays}
760+
Oxalica's Rust overlay has more complete examples of `shell.nix` (and cross compilation) under its
761+
[`examples` directory](https://github.com/oxalica/rust-overlay/tree/e53e8853aa7b0688bc270e9e6a681d22e01cf299/examples).
731762

732-
There are two community maintained approaches to Rust toolchain management:
733-
- [oxalica's Rust overlay](https://github.com/oxalica/rust-overlay)
734-
- [fenix](https://github.com/nix-community/fenix)
735-
736-
Oxalica's overlay allows you to select a particular Rust version and components.
737-
See [their documentation](https://github.com/oxalica/rust-overlay#rust-overlay) for more
738-
detailed usage.
763+
### Using Rust nightly in a derivation with `buildRustPackage` {#using-rust-nightly-in-a-derivation-with-buildrustpackage}
739764

740-
Fenix is an alternative to `rustup` and can also be used as an overlay.
741-
742-
Both oxalica's overlay and fenix better integrate with nix and cache optimizations.
743-
Because of this and ergonomics, either of those community projects
744-
should be preferred to the Mozilla's Rust overlay (`nixpkgs-mozilla`).
765+
You can also use Rust nightly to build rust packages using `makeRustPlatform`.
766+
The below snippet demonstrates invoking `buildRustPackage` with a Rust toolchain from oxalica's overlay:
745767

746-
### How to select a specific `rustc` and toolchain version {#how-to-select-a-specific-rustc-and-toolchain-version}
747-
748-
You can consume the oxalica overlay and use it to grab a specific Rust toolchain version.
749-
Here is an example `shell.nix` showing how to grab the current stable toolchain:
750768
```nix
751-
{ pkgs ? import <nixpkgs> {
752-
overlays = [
753-
(import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
754-
];
755-
}
756-
}:
757-
pkgs.mkShell {
758-
nativeBuildInputs = with pkgs; [
759-
pkg-config
760-
rust-bin.stable.latest.minimal
761-
];
762-
}
763-
```
764-
765-
You can try this out by:
766-
1. Saving that to `shell.nix`
767-
2. Executing `nix-shell --pure --command 'rustc --version'`
768-
769-
As of writing, this prints out `rustc 1.56.0 (09c42c458 2021-10-18)`.
770-
771-
### How to use an overlay toolchain in a derivation {#how-to-use-an-overlay-toolchain-in-a-derivation}
772-
773-
You can also use an overlay's Rust toolchain with `buildRustPackage`.
774-
The below snippet demonstrates invoking `buildRustPackage` with an oxalica overlay selected Rust toolchain:
775-
```nix
776-
with import <nixpkgs> {
769+
with import <nixpkgs>
770+
{
777771
overlays = [
778772
(import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
779773
];
780774
};
775+
let
776+
rustPlatform = makeRustPlatform {
777+
cargo = rust-bin.stable.latest.minimal;
778+
rustc = rust-bin.stable.latest.minimal;
779+
};
780+
in
781781
782782
rustPlatform.buildRustPackage rec {
783783
pname = "ripgrep";
784784
version = "12.1.1";
785-
nativeBuildInputs = [
786-
rust-bin.stable.latest.minimal
787-
];
788785
789786
src = fetchFromGitHub {
790787
owner = "BurntSushi";
791788
repo = "ripgrep";
792789
rev = version;
793-
hash = "sha256-1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps=";
790+
hash = "sha256-+s5RBC3XSgb8omTbUNLywZnP6jSxZBKSS1BmXOjRF8M=";
794791
};
795792
796-
cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp";
793+
cargoHash = "sha256-l1vL2ZdtDRxSGvP0X/l3nMw8+6WF67KPutJEzUROjg8=";
794+
795+
doCheck = false;
797796
798797
meta = with lib; {
799798
description = "A fast line-oriented regex search tool, similar to ag and ack";
800799
homepage = "https://github.com/BurntSushi/ripgrep";
801-
license = licenses.unlicense;
802-
maintainers = [ maintainers.tailhook ];
800+
license = with licenses; [ mit unlicense ];
801+
maintainers = with maintainers; [ tailhook ];
803802
};
804803
}
805804
```
806805

807806
Follow the below steps to try that snippet.
808-
1. create a new directory
809807
1. save the above snippet as `default.nix` in that directory
810-
1. cd into that directory and run `nix-build`
811-
812-
### Rust overlay installation {#rust-overlay-installation}
813-
814-
You can use this overlay by either changing your local nixpkgs configuration,
815-
or by adding the overlay declaratively in a nix expression, e.g. in `configuration.nix`.
816-
For more information see [the manual on installing overlays](#sec-overlays-install).
817-
818-
### Declarative Rust overlay installation {#declarative-rust-overlay-installation}
819-
820-
This snippet shows how to use oxalica's Rust overlay.
821-
Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:
822-
823-
```nix
824-
{ pkgs ? import <nixpkgs> {
825-
overlays = [
826-
(import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
827-
# Further overlays go here
828-
];
829-
};
830-
};
831-
```
808+
2. cd into that directory and run `nix-build`
832809

833-
Note that this will fetch the latest overlay version when rebuilding your system.
810+
Fenix also has examples with `buildRustPackage`,
811+
[crane](https://github.com/ipetkov/crane),
812+
[naersk](https://github.com/nix-community/naersk),
813+
and cross compilation in its [Examples](https://github.com/nix-community/fenix#examples) section.

0 commit comments

Comments
 (0)