Following [Best Practices](https://nix.dev/guides/best-practices#with-scopes),
`with` is a problematic language construction and should be avoided.
Usually it is employed like a "factorization": `[ X.A X.B X.C X.D ]` is written
`with X; [ A B C D ]`.
However, as shown in the link above, the syntatical rules of `with` are not so
intuitive, and this "distributive rule" is very selective, in the sense that
`with X; [ A B C D ]` is not equivalent to `[ X.A X.B X.C X.D ]`.
However, this factorization is still useful to "squeeze" some code, especially
in lists like `meta.maintainers`.
On the other hand, it becomes less justifiable in bigger scopes. This is
especially true in cases like `with lib;` in the top of expression and in sets
like `meta = with lib; { . . . }`.
That being said, this patch removes most of example code in the current
documentation.
The exceptions are, for now
- doc/functions/generators.section.md
- doc/languages-frameworks/coq.section.md
because, well, they are way more complicated, and I couldn't parse them
mentally - yet another reason why `with` should be avoided!
Fixes some mistakes regarding the references to cargoHash in the codes referenced.
Fixes a typo for cargoSha256.
States that cargoHash should be preferred.
We keep running into situations where we can't get the right
combination of rustc flags through build systems into rustc.
RUSTFLAGS is the only variable supported across build systems, but if
RUSTFLAGS is set, Cargo will ignore all other ways of specifying rustc
flags, including the target-specific ones, which we need to make
dynamic musl builds work. (This is why pkgsCross.musl64.crosvm is
currently broken — it works if you unset separateDebugInfo, which
causes RUSTFLAGS not to be set.)
So, we need to do the same thing we do for C and C++ compilers, and
add a compiler wrapper so we can inject the flags we need, regardless
of the build system.
Currently the wrapper only supports a single mechanism for injecting
flags — the NIX_RUSTFLAGS environment variable. As time goes on,
we'll probably want to add additional features, like target-specific
environment variables.
The headings for the Rust section are structured incorrectly in two ways:
1. The section "Compiling non-Rust packages that include Rust code" is totally specific to `buildRustPackage`. It should be a child of the "Compiling Rust applications with Cargo" section.
1. The section "Setting up `nix-shell`" is totally specific to `buildRustCrate`. It should be a child of the "Compiling Rust crates using Nix instead of Cargo" section.
- Rust
- Compiling Rust applications with Cargo
- ...
- Compiling non-Rust packages that include Rust code
- ...
- Compiling Rust crates using Nix instead of Cargo
- ...
- Setting Up `nix-shell`
- ...
- Rust
- Compiling Rust applications with Cargo
- ...
- Compiling non-Rust packages that include Rust code
- ...
- Compiling Rust crates using Nix instead of Cargo
- ...
- Setting Up `nix-shell`
- ...
The nixpkgs manual contains references to both sri hash and explicit
sha256 attributes. This is at best confusing to new users. Since the
final destination is exclusive use of sri hashes, see nixos/rfcs#131,
might as well push new users in that direction gently.
Notable exceptions to sri hash support are builtins.fetchTarball,
cataclysm-dda, coq, dockerTools.pullimage, elixir.override, and
fetchCrate. None, other than builtins.fetchTarball, are fundamentally
incompatible, but all currently accept explicit sha256 attributes as
input. Because adding backwards compatibility is out of scope for this
change, they have been left intact, but migration to sri format has been
made for any using old hash formats.
All hashes have been manually tested to be accurate, and updates were
only made for missing upstream artefacts or bugs.
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"
I found out how to use aspell with a custom dictionary and so ran that
on `rust.section.md`.
These changes are trivial consistency in spelling and nomenclature.
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` :)
As far as I can tell, a8efb2053f removed
the `target =` escape hatch.
See #112804
This commit removes it from the documentation.
Signed-off-by: Arthur Gautier <baloo@superbaloo.net>
