diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
index 66f821ea21a3..04b43b5c272f 100644
--- a/doc/languages-frameworks/rust.section.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -254,7 +254,7 @@ By default, it takes the `stdenv.hostPlatform.config` and replaces components
 where they are known to differ. But there are ways to customize the argument:
 
  - To choose a different target by name, define
-   `stdenv.hostPlatform.rust.rustcTarget` as that name (a string), and that
+   `stdenv.hostPlatform.rust.rustcTargetSpec` as that name (a string), and that
    name will be used instead.
 
    For example:
@@ -262,7 +262,7 @@ where they are known to differ. But there are ways to customize the argument:
    ```nix
    import <nixpkgs> {
      crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // {
-       rust.rustcTarget = "thumbv7em-none-eabi";
+       rust.rustcTargetSpec = "thumbv7em-none-eabi";
      };
    }
    ```
@@ -274,22 +274,24 @@ where they are known to differ. But there are ways to customize the argument:
    ```
 
  - To pass a completely custom target, define
-   `stdenv.hostPlatform.rust.rustcTarget` with its name, and
-   `stdenv.hostPlatform.rust.platform` with the value.  The value will be
-   serialized to JSON in a file called
-   `${stdenv.hostPlatform.rust.rustcTarget}.json`, and the path of that file
-   will be used instead.
+   `stdenv.hostPlatform.rust.rustcTargetSpec` with the path to the custom
+   target specification JSON file.
+
+   Note that some tools like Cargo and some crates like `cc` make use of the
+   file name of the target JSON.  Therefore, do not use
+   `./path/to/target-spec.json` directly, because it will be renamed by Nix.
+   Instead, place it a directory and use `"${./path/to/dir}/target-spec.json"`.
+   The directory should contain only this one file, to avoid unrelated changes
+   causing unnecessary rebuilds.
 
    For example:
 
    ```nix
    import <nixpkgs> {
-     crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // {
-       rust.rustcTarget = "thumb-crazy";
-       rust.platform = {
-         foo = "";
-         bar = "";
-       };
+     crossSystem = {
+       config = "mips64el-unknown-linux-gnuabi64";
+       # gcc = ...; # Config for C compiler omitted
+       rust.rustcTargetSpec = "${./rust}/mips64el_mips3-unknown-linux-gnuabi64.json";
      };
    }
    ```
@@ -297,12 +299,9 @@ where they are known to differ. But there are ways to customize the argument:
    will result in:
 
    ```shell
-   --target /nix/store/asdfasdfsadf-thumb-crazy.json # contains {"foo":"","bar":""}
+   --target /nix/store/...-rust/mips64el_mips3-unknown-linux-gnuabi64.json
    ```
 
-Note that currently custom targets aren't compiled with `std`, so `cargo test`
-will fail. This can be ignored by adding `doCheck = false;` to your derivation.
-
 ### Running package tests {#running-package-tests}
 
 When using `buildRustPackage`, the `checkPhase` is enabled by default and runs