Commit Graph

112 Commits

Author SHA1 Message Date
Anderson Torres
e671d3bbbd Nix docs: remove with lib; from example code
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!
2024-03-06 11:40:09 -03:00
Leon
0bb74f147b
doc: small fix for nightly in derivation snippet (#292688) 2024-03-04 15:44:39 -08:00
Justin "J.R." Hill
0f7d690e48
doc: consistently prefer and lead with cargoHash over cargSha256 2024-02-08 15:41:32 -08:00
github-actions[bot]
dc4a7c97b0
Merge master into staging-next 2024-01-18 18:00:55 +00:00
Peder Bergebakken Sundt
e07a2fab7f stdenv: substituteStream: deprecate --replace in favor of --replace-{fail,warn,quiet} 2024-01-14 22:07:58 +01:00
Gabriel Lopes Rodrigues
d3a7f45716 doc: update buildRustPackage documentation
Fixes some mistakes regarding the references to cargoHash in the codes referenced.
Fixes a typo for cargoSha256.
States that cargoHash should be preferred.
2023-12-21 22:01:17 -03:00
Alyssa Ross
8b51cdd3be rustc: add a compiler wrapper
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.
2023-11-30 09:23:06 +00:00
Adam Joseph
d43e8d5549
Update doc/languages-frameworks/rust.section.md
Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
2023-11-12 09:31:39 +00:00
Adam Joseph
ae7b2678f3 rust: add tutorial on git-bisecting rustc
This commits adds to the manual a tutorial showing how to
troubleshoot breakage caused by a rustc upgrade in *downstream*
packages.
2023-11-11 22:12:58 -08:00
Valentin Gagarin
61fa1255f8 link to documentation on IFD in the Nix manual 2023-10-09 23:57:03 +02:00
nicoo
fe138d36c9 doc: Replace sha256 with hash where appropriate 2023-09-13 17:24:49 +00:00
Jan Malakhovski
ccbb065c88 doc: make sourceRoot and setSourceRoot documentation match the implementation, fix examples 2023-08-03 16:32:05 +00:00
Paul Colomiets
366404a9d3 Remove tailhook from maintainers 2023-07-22 14:11:29 +03:00
Alyssa Ross
5e06b3cb19 treewide: don't use rustPlatform.rust
This will be deprecated in the next commit.
2023-05-12 15:31:21 +00:00
figsoda
e7e93bd709 docs/rust: prefer ln -s over cp 2023-04-04 21:21:28 -04:00
Yureka
f3a1640e49 docs/rust: add note about git dependencies 2023-03-26 01:52:04 +01:00
Adam Joseph
e369d78b70 remove references to crate2nix other than a link to its docs 2023-03-17 12:13:13 -07:00
Adam Joseph
618d8e6a62
Update doc/languages-frameworks/rust.section.md
Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
2023-03-17 19:10:15 +00:00
Adam Joseph
4716768513
Update doc/languages-frameworks/rust.section.md
Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
2023-03-17 19:09:50 +00:00
Adam Joseph
50f57ac692 doc/../rust.section.md: fix incorrect header depths
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`
      - ...
2023-03-15 19:42:54 -07:00
Adam Joseph
efbbdc16e6 Revert "carnix,cratesIO: remove" in doc/languages-frameworks/rust.section.md
This reverts the part of commit
82fe76d1cd that affected
doc/languages-frameworks/rust.section.md
2023-03-15 19:41:48 -07:00
figsoda
b373d299ba docs/rust: improve docs for nightly usage 2023-03-03 22:46:28 -05:00
figsoda
b6c0e7f563
Merge pull request #205935 from figsoda/cargo-lock
rustPlatform.importCargoLock: add allowBuiltinFetchGit option
2022-12-25 19:38:36 -05:00
figsoda
403e25e3e3 doc: fix typos 2022-12-17 18:21:48 -05:00
figsoda
cce3dc63a0 rustPlatform.importCargoLock: add allowBuiltinFetchGit option 2022-12-13 11:27:26 -05:00
Jörg Thalheim
c0491d5fd2
Merge pull request #204343 from urandom2/sridoc
doc: use sri hash syntax
2022-12-04 10:04:57 +01:00
Colin Arnott
bac379f30a
doc: use sri hash syntax
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.
2022-12-04 06:12:18 +00:00
figsoda
0f386d1896 docs/rust: document cargoNextestHook and useNextest 2022-11-28 18:30:30 -05:00
figsoda
82fe76d1cd carnix,cratesIO: remove 2022-11-22 14:10:25 -05:00
Artturi
80212614a3
Merge pull request #187921 from amjoseph-nixpkgs/pr/manual/rust/buildRustY
doc/../rust.section.md: prominently mention `buildRustXX` names
2022-11-21 19:08:38 +02:00
0x4A6F
b37df78bfe
doc/languages-frameworks/rust: example for disabling tests (#198705) 2022-10-31 22:39:34 +01:00
Ian Macalinao
30a5965216
doc/languages-frameworks/rust: fix typo 2022-09-03 15:45:21 -05:00
Adam Joseph
aad7f1d6b3 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"
2022-08-22 14:37:41 -07:00
Guillaume Girol
bedabfbcef rustPlatform.bindgenHook: init 2022-02-22 19:37:07 +01:00
Andreas Stührk
192fcbd32a docs: Fix markdown in Rust language section 2021-12-18 14:05:46 +01:00
github-actions[bot]
933da575d4
Merge master into staging-next 2021-11-05 18:01:07 +00:00
Eli Flanagan
933f117a78
docs: Rust language section consistency
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.
2021-11-05 10:40:59 -04:00
github-actions[bot]
ac4cb43546
Merge staging-next into staging 2021-11-05 00:02:01 +00:00
Eli Flanagan
7bffde6dbc
docs: fix Rust language typos
I tried to use aspell following https://github.com/NixOS/nixpkgs/issues/34308#issuecomment-361431632 but there are too many false positives!
2021-11-04 16:19:01 -04:00
github-actions[bot]
20bee66ec8
Merge staging-next into staging 2021-11-04 18:01:44 +00:00
Eli Flanagan
326cfefd68 Apply suggestions from code review
Co-authored-by: Sandro <sandro.jaeckel@gmail.com>
2021-11-05 00:17:56 +09:00
Eli Flanagan
b829fe48e3 add an example with buildRustPackage 2021-11-05 00:17:56 +09:00
Eli Flanagan
8650a7e6e1 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` :)
2021-11-05 00:17:56 +09:00
figsoda
62d502d703 doc/rust: add documentation for feature options 2021-10-27 09:24:19 -04:00
Arthur Gautier
c1a440b6cc doc: rust: target escape hatch has been removed
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>
2021-10-19 05:38:45 +00:00
Robin Stumm
5b0a3115c8 doc: rust: rephrase paragraph about cargoLock.lockFileContents
mentioning that `Cargo.lock` cannot be patched in the `patchPhase`
2021-09-22 20:32:19 +09:00
Robin Stumm
4771684208 doc: rust: simplify snippet
Do not use recursive attribute sets where not needed, it could confuse the reader.
2021-09-22 20:32:19 +09:00
Robin Stumm
4ab63a8ca8 doc: rust: improve clarity of example snippet
Make it more clear that the return type is a string.

Co-authored-by: figsoda <figsoda@pm.me>
2021-09-22 20:32:19 +09:00
Robin Stumm
4ecb3e8795 doc: rust: document cargoLock.lockFileContents 2021-09-22 20:32:19 +09:00
Markus S. Wamser
b06ffb4b45 doc/rust: add missing fetchfromGitHub to derivation example 2021-09-19 16:41:11 +00:00