doc/../rust.section.md: prominently mention buildRustXX names

This was a source of massive confusion for me when I first learned my way around nixpkgs' rust machinery.  I seek to save others from that confusion.

* `buildRustPackage` should have been named `buildRustPackageUsingCargo`

* `buildRustCrate` should have been named `buildRustPackageUsingNix`

It is, unfortunately, too late to fix this.  Let's do the next best thing and make the names `buildRustPackage` and `buildRustCrate` very prominent in the documentation, so readers see immediately that they need to learn the following jargon:

* `buildRustPackage` means "build this Rust crate by calling `cargo` in one (or two) monolithic derivations"

* `buildRustCrate` means "build this Rust crate by calling `rustc` in one derivation for each crate"
This commit is contained in:
Adam Joseph 2022-08-22 14:37:41 -07:00
parent 97d1ae99de
commit aad7f1d6b3

View File

@ -15,7 +15,7 @@ For other versions such as daily builds (beta and nightly),
use either `rustup` from nixpkgs (which will manage the rust installation in your home directory),
or use a community maintained [Rust overlay](#using-community-rust-overlays).
## Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo}
## `buildRustPackage`: Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo}
Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
@ -596,7 +596,7 @@ buildPythonPackage rec {
}
```
## Compiling Rust crates using Nix instead of Cargo {#compiling-rust-crates-using-nix-instead-of-cargo}
## `buildRustCrate`: Compiling Rust crates using Nix instead of Cargo {#compiling-rust-crates-using-nix-instead-of-cargo}
### Simple operation {#simple-operation}