From e471233057afb6b7d1d9af8ed76d8ebdbed84e72 Mon Sep 17 00:00:00 2001
From: oxalica <oxalicc@pm.me>
Date: Tue, 6 Apr 2021 00:39:42 +0800
Subject: [PATCH] Update README for profiles

---
 README.md | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 057a50a39af..ffe2c2a0f05 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ Here's an example of using it in nixos configuration.
     distRoot = "https://static.rust-lang.org/dist";
 
     # Select a toolchain and aggregate components by rustup's `rust-toolchain` file format.
-    # See: https://github.com/ebroto/rustup/blob/c2db7dac6b38c99538eec472db9d23d18f918409/README.md#the-toolchain-file
+    # See: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
     fromRustupToolchain = { channel, components ? [], targets ? [] }: «derivation»;
     # Same as `fromRustupToolchain` but read from a `rust-toolchain` file (legacy one-line string or in TOML).
     fromRustupToolchainFile = rust-toolchain-file-path: «derivation»;
@@ -101,8 +101,18 @@ Here's an example of using it in nixos configuration.
     stable = {
       # The latest stable toolchain.
       latest = {
-        # Aggregate all default components. (recommended)
+        # [Experimental]
+        # Profiles, predefined component sets.
+        # See: https://rust-lang.github.io/rustup/concepts/profiles.html
+        minimal = «derivation»;  # Only `cargo`, `rustc` and `rust-std`.
+        default = «derivation»;  # The default profile of `rustup`. Good for general use.
+        complete = «derivation»; # Do not use it. It almost always fails.
+
+        # Pre-aggregated package provided by upstream, the most commonly used package in `mozilla-overlay`.
+        # It consists of an uncertain number of components, usually more than the `default` profile of `rustup`
+        # but less than `complete` profile.
         rust = «derivation»;
+
         # Individial components.
         rustc = «derivation»;
         cargo = «derivation»;
@@ -144,8 +154,15 @@ Here's an example of using it in nixos configuration.
 
 Some examples (assume `nixpkgs` had the overlay applied):
 
-- Latest stable/beta/nightly rust with all default components:
+- Latest stable/beta/nightly rust with almost all components (provided the same as `mozilla-overlay`):
   `nixpkgs.rust-bin.{stable,beta,nightly}.latest.rust`
+- *\[Experimental\]*
+  Latest stable/beta/nightly rust with `default` or `minimal` profile (provided the same as default behavior of `rustup install`).
+  `nixpkgs.rust-bin.{stable,beta,nightly}.latest.{default,minimal}`
+
+  Note: `default` profile on `nightly` may not always be available due to absense of required components.
+  You can check availability on [Rustup packages availibility](https://rust-lang.github.io/rustup-components-history/).
+
 - A specific version of stable rust:
   `nixpkgs.rust-bin.stable."1.48.0".rust`
 - A specific date of beta rust:
@@ -163,12 +180,14 @@ Some examples (assume `nixpkgs` had the overlay applied):
     targets = [ "arm-unknown-linux-gnueabihf" ];
   }
   ```
-- If you already have a [`rust-toolchain` file for rustup](https://github.com/ebroto/rustup/blob/c2db7dac6b38c99538eec472db9d23d18f918409/README.md#the-toolchain-file),
+
+- If you already have a [`rust-toolchain` file for rustup][rust-toolchain],
   you can simply use `fromRustupToolchainFile` to get the customized toolchain derivation.
 
   ```nix
   nixpkgs.rust-bin.fromRustupToolchainFile ./rust-toolchain
   ```
+
 - *\[Experimental\]*
   Toolchain with specific rustc git revision.
   This is useful for development of rust components like [MIRI](https://github.com/rust-lang/miri).
@@ -182,8 +201,10 @@ Some examples (assume `nixpkgs` had the overlay applied):
     };
   }
   ```
+
 - See more examples in directory `examples`.
 
 For more details, see also the source code of `./rust-overlay.nix`.
 
 [mozilla]: https://github.com/mozilla/nixpkgs-mozilla
+[rust-toolchain]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file