| Age | Commit message (Collapse) | Author | Files | Lines |
|---|
|
* doc/stdenv: document prefixKey more precisely
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
This reverts commit 7e1443abbba99e9dac29ce2ad01c1c4e4fb66070.
|
|
stdenv: add meta.repository field
|
|
|
|
This allows for correct highlighting and maybe future automatic
formatting. The AST was verified to work with nixfmt only.
|
|
This should help us with highlighting and future formatting.
|
|
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!
|
|
|
|
--replace-{fail,warn,quiet}
|
|
https://www.pcre.org/
The `pcre` library is "now at end of life, and is no longer being
maintained," according to the upstream maintainers. Accordingly, we
should replace uses of `pcre` with its actively maintained successor,
`pcre2`, wherever possible .
|
|
doc: diagram explaining what it means for a dependency to be propagated
|
|
|
|
doc: clarify stdenv phase flag attributes
|
|
Extended genericBuild description
|
|
|
|
Update instructions for manual build phases execution via `nix-shell` to
cover all phases. There is no easy way of getting those commands, so it
makes a sense to have them all properly documented.
|
|
While the word 'simply' is usually added to encourage readers, it often has the
opposite effect and may even appear condescending, especially when the reader
runs into trouble trying to apply the suggestions from the documentation. It is
almost always an improvement to simply drop the word from the sentence.
(there are more possible improvements like this, we can apply those in separate
PRs)
|
|
arguments in stdenv
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
(#262137)
* doc/stdenv: rewrite manual build procedure to be closer to an auto-build
This is based on
<https://jade.fyi/blog/building-nix-derivations-manually/> plus some
more original research.
The previous version of this section did not work for your choice of
simple Haskell package, e.g. haskellPackages.hscolour, due to things
like `compileBuildDriverPhase` and other custom phases that it
does not address at all.
It seems more correct to use genericBuild in development to harmonize it
with what is actually done.
I feel a little bit like I am committing a sin by suggesting using the
experimental CLI in the manual (afaict I am the first to do this), but I
have given the old version of the command, and there are justifiable
reasons to do it:
* The noted limitations with env-vars are fixed. The one with the
non-empty temp directory was one I ran into myself and oh boy was that
not fun to debug.
* Additionally the outputs are set *before* sourcing `setup.sh`: there
is an issue with nix-shell where the original version of `$out` winds
up in `NIX_LDFLAGS` due to _addRpathPrefix, which means that resulting
executables may not run properly.
It is sad that `nix develop` propagates a wrong value of `SHELL` to
builders, though. It is equally sad that `nix-shell` is essentially
abandoned upstream, with undocumented and not insignificant differences
from `nix develop`.
For the exact script differences:
https://github.com/NixOS/nix/blob/17e6b85d05b3d32df244b1d4e89aa41fd8bdcae8/src/nix-build/nix-build.cc#L516-L551
https://github.com/NixOS/nix/blob/db026103b18fb8b5a719594502edd0f89eb9c268/src/nix/get-env.sh
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
* nixpkgs manual: add an alternative example in stdenv-separateDebugInfo
This change gets rid of the indirect reference to `nix-env -i` usage
and shows how to achieve the same goal with a shell expression.
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
`-z bindnow` doesn't exist. The actual flag added is `-z now`.
|
|
The text was originally added [0] following an apparently incomplete
research on how everything plays together. In fact, Nix propagates
`outputs` to the corresponding nested derivations, and there is some
messy behavior in Nixpkgs that only seems to propagate
`meta.outputsToInstall` in `buildEnv`[1].
This change moves the hints on how to use NixOS specifics to NixOS
module documentation (which is hopefully easier to find through
search.nixos.org), describes the default behavior in Nixpkgs (updating
a the link to the source), and removes the confusing mention of
`nix-env`.
the last of them should not be there to begin with. we don't want
beginners to use `nix-env`, as this is known to run them into trouble
eventually.
[0]: https://github.com/NixOS/nixpkgs/pull/76794
[1]: https://github.com/NixOS/nixpkgs/blob/1774d07242995050d2d8a91cb4da0855eac2e472/pkgs/build-support/buildenv/default.nix#L66
|
|
|
|
Instead of just telling the reader to go find the relevant section of the Nix
manual, let's just link to it. Yay hypertext!
|
|
* Updates meta.chapter.md with a reference link to the usage of the package description field instead of referring to nix-env
---------
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
|
|
|
|
|
|
|
|
nixpkgs-update
|
|
|
|
implementation, fix examples
|
|
|
|
also updates nixdoc to 2.3.0. the nixdoc update is not a separate commit
because that would leave the manual build broken for one commit,
potentially breaking bisects and rebases.
|
|
|
|
|
|
pandoc recognizes `::: note` admonitions, nixos-render-docs only
recognizes `::: {.note}`. surprisingly pandoc also emits the correct
docbook tags for `[](#xref)`s, so we can use that too.
|
|
I read this and expected it to be a timeout that was always applied
when building the derivation, but it's actually a Hydra-specific
thing.
|
|
|
|
t0 is mentioned in the conclusion so we cannot use placeholder in the premise.
|
|
* doc/stdenv/meta.chapter.md: document meta.badPlatforms
We don't have any documentation for the `meta.badPlatforms` attribute.
This commit adds documentation for it.
|
|
doc/stdenv/meta.chapter.md: explain difference between broken and badPlatforms
|
|
|
|
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
|
|
There has been a longstanding ambiguity between `broken` and
`badPlatforms`, which seem to serve overlapping purposes.
This commit adds to the documentation two examples of constraints
which cannot be expressed by `platforms` and `badPlatforms`.
This commit also mentions `NIXPKGS_ALLOW_BROKEN=1` for overriding
`broken`.
|
|
without stable ids on headings we cannot generate stable links to these
headings. nrd complains about this, but the current docbook workflow
does not.
a few generated ids remain, mostly in examples and footnotes. most of
the examples are generated by nixdoc (which has since gained MD export
functions, and the MD export does generate IDs).
|
|
docs/stdenv: Document updateScript features
|
|
This was removed in https://github.com/NixOS/nixpkgs/commit/c1b05442ffd6cf3cf529cad469bebe8169b156e9
for stabilization but it has worked quite well.
|
