Move documentation for impure derivation#8212
Move documentation for impure derivation#8212bryanhonof wants to merge 6 commits intoNixOS:masterfrom
Conversation
.gitignore
Outdated
| /doc/manual/src/command-ref/new-cli | ||
| /doc/manual/src/command-ref/conf-file.md | ||
| /doc/manual/src/command-ref/experimental-features-shortlist.md | ||
| /doc/manual/src/contributing/experimental-feature-descriptions.md |
There was a problem hiding this comment.
This got added in #7798, although I'm not certain how we'd update the description of experimental features then?
There was a problem hiding this comment.
Oh, never mind… it is generated. 😁
|
Do not move. Keep private and add nix developers. Nix was created for urn .
Only help urn . Do not do anything that would incriminate.
…On Wed, Apr 12, 2023, 1:17 PM Bryan Honof ***@***.***> wrote:
Motivation
The documentation of impure derivations was only available under the
experimental features section. The feature adds an attribute to derivation,
so I thought it made sense to also document it under the special attributes
section.
Context
Be more consistent with documenting the attributes available to derivation.
Checklist for maintainers
Maintainers: tick if completed or explain if not relevant
- agreed on idea
- agreed on implementation strategy
- tests, as appropriate
- functional tests - tests/**.sh
- unit tests - src/*/tests
- integration tests - tests/nixos/*
- documentation in the manual
- documentation in the internal API docs
- code and comments are self-explanatory
- commit message explains why the change was made
- new feature or incompatible change: updated release notes
Priorities
Add 👍 to pull requests you find important
<https://github.com/NixOS/nix/pulls?q=is%3Aopen+sort%3Areactions-%2B1-desc>
.
------------------------------
You can view, comment on, or merge this pull request online at:
#8212
Commit Summary
- 7354cc9
<7354cc9>
Refactor impure derivation docs
- e192906
<e192906>
Update experimental feature descriptions
- a101940
<a101940>
Remove experimental feature descriptions from gitignore
File Changes
(3 files <https://github.com/NixOS/nix/pull/8212/files>)
- *M* .gitignore
<https://github.com/NixOS/nix/pull/8212/files#diff-bc37d034bad564583790a46f19d807abfe519c5671395fd494d8cce506c42947>
(1)
- *A* doc/manual/src/contributing/experimental-feature-descriptions.md
<https://github.com/NixOS/nix/pull/8212/files#diff-ee94f8d02def192cafdcd65767ee609a5752459dbe3aab5bb248fe4c47781ca2>
(122)
- *M* doc/manual/src/language/advanced-attributes.md
<https://github.com/NixOS/nix/pull/8212/files#diff-89ccb5a45c954c61749d193629e2d343c5522350af97ee1464046f80d18f20c9>
(37)
Patch Links:
- https://github.com/NixOS/nix/pull/8212.patch
- https://github.com/NixOS/nix/pull/8212.diff
—
Reply to this email directly, view it on GitHub
<#8212>, or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ASYLZ6TZHMKRPYR2DG6QHS3XA3WSNANCNFSM6AAAAAAW4BBMWA>
.
You are receiving this because you are subscribed to this thread.Message
ID: ***@***.***>
|
bryanhonof
force-pushed
the
impure-derivation-docs
branch
from
a101940 to
7354cc9
Compare
|
Good idea! In #8174 I tried to start doing a consistent style for this sort of thing. Whatever we end up with, it would be good to match that with this. |
Co-authored-by: Eelco Dolstra <[email protected]>
There was a problem hiding this comment.
Please let's format markdown with one line per sentence, it makes review a lot easier and minimizes the diff when working on contents.
I agree with @edolstra that the additional information should end up here, but in its current shape it appears to me that it will do more harm than good because it adds so many concepts without any hint at what they actually mean.
In scope of my self-assigned crusade to reduce the potential for confusion in Nix documentation, I think these parts should be left for a follow up, which will probably be non-trivial.
| to the embedded store and not to the host's Nix store. | ||
|
|
||
| - [`__impure`]{#adv-attr-__impure}\ | ||
| > **Warning** |
There was a problem hiding this comment.
Indentation is broken again
| ``` | ||
|
|
||
| Each time this derivation is built it produces a different output, | ||
| since the builder outputs random bytes to $out. The [pull request |
There was a problem hiding this comment.
| since the builder outputs random bytes to $out. The [pull request | |
| since the builder outputs random bytes to `$out`. The [pull request |
| Each time this derivation is built it produces a different output, | ||
| since the builder outputs random bytes to $out. The [pull request | ||
| introducing impure | ||
| derivations](https://github.com/NixOS/nix/pull/6227) has more |
There was a problem hiding this comment.
No, please inline the examples here. PRs cannot be maintained.
| Impure derivations have the following traits: | ||
| - Only impure or fixed-output derivations are allowed to depend on | ||
| impure derivations directly. "Pure" (i.e. input-addressed or | ||
| floating CA derivations) can depend on impure derivations |
There was a problem hiding this comment.
Don't use abbreviations of our own terms, they have to be expected to be not known to readers.
| floating CA derivations) can depend on impure derivations | |
| floating content-addressed derivations) can depend on impure derivations |
Is floating CA defined anywhere? Otherwise this adds more confusion than it removes because readers will tend to either not actually understand anything at all or go on a tour through the internet searching for an explanation of those terms, complaining why everything is so scattered.
| barrier" in the dependency graph. | ||
| - They cannot be | ||
| [content-addressed](@docroot@/contributing/experimental-features.md#xp-feature-ca-derivations) | ||
| - Impure derivations are not "cached". Thus, running "nix-build" |
There was a problem hiding this comment.
Why is cached put in quotes? Is it only quasi caching? What does caching mean here exactly?
| - Impure derivations are not "cached". Thus, running "nix-build" | |
| - Impure derivations are not cached, that is, <answer that question>. Thus, running `nix-build` |
| time. | ||
| - They are implemented similar to CA derivations, i.e. the output | ||
| is moved to a content-addressed path in the store. The | ||
| difference is that we don't register a realisation in the Nix database. |
There was a problem hiding this comment.
CA Realisation is not a defined term in the manual. There is even an issue for that. Given that Realisation means something else with an existing definition, using it here will only lead to confusion.
I don't want to blow up the scope here, but I think referring to non-trivial concepts which are nowhere defined or explained is a net detriment, and for me that constitutes a blocker that has to be resolved first. I suggest that you this part out for now and open an issue to follow up (ideally with all the information that you already had, so it can be picked up by someone easily). @NixOS/documentation-team could help disentangling the tasks that have to be done in order to document these details properly.
| - They are implemented similar to CA derivations, i.e. the output | ||
| is moved to a content-addressed path in the store. The | ||
| difference is that we don't register a realisation in the Nix database. | ||
| - When sandboxing is enabled, impure derivations can access the |
There was a problem hiding this comment.
Please link to the associated configuration setting
|
This issue has been mentioned on NixOS Discourse. There might be relevant details there: |
Some of these are a bit after the specified time period, but I also believe some of these items are difficult to gauge how much "impact" they had. Helped organize, host, and run, the Summer of Nix Lecture Series 2022 - https://www.youtube.com/playlist?list=PLt4-_lkyRrOMWyp5G-m_d1wtTcbBaOxZk - NixOS/infra#213 Helped organize, and host infra for, the Summer of Nix Lecture Series 2023 - https://www.youtube.com/playlist?list=PLt4-_lkyRrOPcBuz_tjm6ZQb-6rJjU3cf - NixOS/infra#240 Helped organize, host, and was responsible for livestreaming infra during, NixCon Paris 2022 - https://www.youtube.com/playlist?list=PLgknCdxP89ReD6gxl755B6G_CI65z4J2e Maintenance of some nixpkgs packages - NixOS/nixpkgs#340223 (contribution after 2024-05-01) - NixOS/nixpkgs#290084 - NixOS/nixpkgs#170089 Organized, and assembled a team for the FOSDEM 2023 Nix/NixOS Devroom - https://discourse.nixos.org/t/fosdem-2023-nix-and-nixos-devroom/23133 Organizer & sole maintainer of the Config Management Camp Nix track - https://discourse.nixos.org/t/config-management-camp-2023-ghent/23455 - https://discourse.nixos.org/t/config-management-camp-2024-ghent/33852 - https://discourse.nixos.org/t/cfgmgmtcamp-2025-is-looking-for-nix-presentations/51658 (contribution after 2024-05-01) Public speaking & spreading awareness of Nix/NixOS - https://youtu.be/gUjvnZ9ZwMs?si=nDiZTCpQj53wwq8P - https://www.youtube.com/watch?v=hNcYPH5Q_pA&t=862s The occasional dabble into the Nix C++ code base - NixOS/nix#11494 (contribution after 2024-05-01) - NixOS/nix#11490 (contribution after 2024-05-01) - NixOS/nix#11489 (contribution after 2024-05-01) - NixOS/nix#11349 (contribution after 2024-05-01) - NixOS/nix#11241 (contribution after 2024-05-01) - NixOS/nix#9557 - NixOS/nix#8788 - NixOS/nix#8212 - NixOS/nix#5147 General evangelism Pretty much every event I attend, I'm talking about Nix, showing off Nix/NixOS, and just trying to get people to see how awesome this tool is.
6 participants
Motivation
The documentation of impure derivations was only available under the experimental features section. The feature adds an attribute to derivation, so I thought it made sense to also document it under the special attributes section.
Context
Be more consistent with documenting the attributes available to derivation.
Checklist for maintainers
Maintainers: tick if completed or explain if not relevant
tests/**.shsrc/*/teststests/nixos/*Priorities
Add 👍 to pull requests you find important.