docs: improve, clean up Rust language advice

This stems from a discussion [here](https://discourse.nixos.org/t/what-rust-overlay-do-you-use-and-why-advice-appreciated/15412)

I removed an entire section because I feel like that duplicated
Mozilla's original instructions on how to consume the overlay.

The goal here is to simply the "getting started with Rust" in a nix or
NixOS environment.

I will try to do some follow up work to update the code snippets and
output. nightly is on `1.57.0-nightly` :)

authored by Eli Flanagan and committed by Raphael Megzari 8650a7e6 8dd2f31e

+43 -53
+43 -53
doc/languages-frameworks/rust.section.md
··· 13 14 For other versions such as daily builds (beta and nightly), 15 use either `rustup` from nixpkgs (which will manage the rust installation in your home directory), 16 - or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay). 17 18 ## Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo} 19 ··· 871 872 To see that you are using nightly. 873 874 - ## Using the Rust nightlies overlay {#using-the-rust-nightlies-overlay} 875 876 - Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope. 877 - This overlay can _also_ be used to install recent unstable or stable versions 878 - of Rust, if desired. 879 880 - ### Rust overlay installation {#rust-overlay-installation} 881 882 - You can use this overlay by either changing your local nixpkgs configuration, 883 - or by adding the overlay declaratively in a nix expression, e.g. in `configuration.nix`. 884 - For more information see [the manual on installing overlays](#sec-overlays-install). 885 886 - #### Imperative rust overlay installation {#imperative-rust-overlay-installation} 887 888 - Clone [nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla), 889 - and create a symbolic link to the file 890 - [rust-overlay.nix](https://github.com/mozilla/nixpkgs-mozilla/blob/master/rust-overlay.nix) 891 - in the `~/.config/nixpkgs/overlays` directory. 892 893 - ```ShellSession 894 - $ git clone https://github.com/mozilla/nixpkgs-mozilla.git 895 - $ mkdir -p ~/.config/nixpkgs/overlays 896 - $ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix 897 ``` 898 899 - ### Declarative rust overlay installation {#declarative-rust-overlay-installation} 900 901 Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar: 902 903 ```nix 904 { pkgs ? import <nixpkgs> { 905 overlays = [ 906 - (import (builtins.fetchTarball https://github.com/mozilla/nixpkgs-mozilla/archive/master.tar.gz)) 907 # Further overlays go here 908 ]; 909 }; ··· 911 ``` 912 913 Note that this will fetch the latest overlay version when rebuilding your system. 914 - 915 - ### Rust overlay usage {#rust-overlay-usage} 916 - 917 - The overlay contains attribute sets corresponding to different versions of the rust toolchain, such as: 918 - 919 - * `latest.rustChannels.stable` 920 - * `latest.rustChannels.nightly` 921 - * a function `rustChannelOf`, called as `(rustChannelOf { date = "2018-04-11"; channel = "nightly"; })`, or... 922 - * `(nixpkgs.rustChannelOf { rustToolchain = ./rust-toolchain; })` if you have a local `rust-toolchain` file (see https://github.com/mozilla/nixpkgs-mozilla#using-in-nix-expressions for an example) 923 - 924 - Each of these contain packages such as `rust`, which contains your usual rust development tools with the respective toolchain chosen. 925 - For example, you might want to add `latest.rustChannels.stable.rust` to the list of packages in your configuration. 926 - 927 - Imperatively, the latest stable version can be installed with the following command: 928 - 929 - ```ShellSession 930 - $ nix-env -Ai nixpkgs.latest.rustChannels.stable.rust 931 - ``` 932 - 933 - Or using the attribute with nix-shell: 934 - 935 - ```ShellSession 936 - $ nix-shell -p nixpkgs.latest.rustChannels.stable.rust 937 - ``` 938 - 939 - Substitute the `nixpkgs` prefix with `nixos` on NixOS. 940 - To install the beta or nightly channel, "stable" should be substituted by 941 - "nightly" or "beta", or 942 - use the function provided by this overlay to pull a version based on a 943 - build date. 944 - 945 - The overlay automatically updates itself as it uses the same source as 946 - [rustup](https://www.rustup.rs/).
··· 13 14 For other versions such as daily builds (beta and nightly), 15 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). 17 18 ## Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo} 19 ··· 871 872 To see that you are using nightly. 873 874 + ## Using community Rust overlays {#using-community-rust-overlays} 875 876 + There are two community maintained approaches to Rust toolchain management: 877 + - [oxalica's Rust overlay](https://github.com/oxalica/rust-overlay) 878 + - [fenix](https://github.com/nix-community/fenix) 879 880 + Oxalica's overlay allows you to select a particular Rust version and components. 881 + See [their documentation](https://github.com/oxalica/rust-overlay#rust-overlay) for more 882 + detailed usage. 883 884 + Fenix is an alternative to `rustup` and can also be used as an overlay. 885 886 + Both Oxalica's overlay and fenix better integrate with nix and cache optimizations. 887 + Because of this and ergonomics, either of those community projects 888 + should be preferred to the Mozilla's Rust overlay (nixpkgs-mozilla). 889 890 + ### How to select a specific rustc and toolchain version {#how-to-select-a-specific-rustc-and-toolchain-version} 891 892 + You can consume the oxalica overlay and use it to grab a specific Rust toolchain version. 893 + Here is an example `shell.nix` showing how to grab the current stable toolchain: 894 + ```nix 895 + { pkgs ? import <nixpkgs> { 896 + overlays = [ 897 + (import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) 898 + ]; 899 + } 900 + }: 901 + pkgs.mkShell { 902 + nativeBuildInputs = with pkgs; [ 903 + pkg-config 904 + rust-bin.stable.latest.minimal 905 + ]; 906 + } 907 ``` 908 909 + You can try this out by: 910 + 1. Saving that to `shell.nix` 911 + 2. Executing `nix-shell --pure --command 'rustc --version'` 912 913 + As of writing, this prints out `rustc 1.56.0 (09c42c458 2021-10-18)`. 914 + 915 + ### Rust overlay installation {#rust-overlay-installation} 916 + 917 + You can use this overlay by either changing your local nixpkgs configuration, 918 + or by adding the overlay declaratively in a nix expression, e.g. in `configuration.nix`. 919 + For more information see [the manual on installing overlays](#sec-overlays-install). 920 + 921 + ### Declarative Rust overlay installation {#declarative-rust-overlay-installation} 922 + 923 + This snippet shows how to use oxalica's Rust overlay. 924 Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar: 925 926 ```nix 927 { pkgs ? import <nixpkgs> { 928 overlays = [ 929 + (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) 930 # Further overlays go here 931 ]; 932 }; ··· 934 ``` 935 936 Note that this will fetch the latest overlay version when rebuilding your system.