doc/stdenv: add a note about __structuredAttrs

[jackrosenberg]

since NixOS/nixpkgs-vet#203, CI will fail for new top level packages that do not enable __structuredAttrs. AFAIK there is little to no up to date documentation on this.

Not exactly my area of expertise, so if somebody has a better explanation on what __structuredAttrs does, feel free to drop a comment!

closes #509957, NixOS/nix#14847
based on #354949

Things done

• Built on platform:
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• Tested, as applicable:
  • NixOS tests in nixos/tests.
  • Package tests at passthru.tests.
  • Tests in lib/tests or pkgs/test for functions and "core" functionality.
• Ran nixpkgs-review on this PR. See nixpkgs-review usage.
• Tested basic functionality of all binary files, usually in ./result/bin/.
• Nixpkgs Release Notes
  • Package update: when the change is major or breaking.
• NixOS Release Notes
  • Module addition: when adding a new NixOS module.
  • Module update: when the change is significant.
• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

[kirillrdy]

@jackrosenberg have you seen https://nix.dev/manual/nix/2.31/language/advanced-attributes.html#adv-attr-structuredAttrs

[jackrosenberg]

yea i found it there, but since it now affects nixpkgs/nixos i thought it would be good to add it here too. Is it okay to link to other manuals from this one, or is each manual supposed to work offline?

[MattSturgeon]

have you seen [...]

I just commented something similar over on the related issue:

__structuredAttrs is a nix feature, not a nixpkgs feature. Its primary documentation should be in the nix manual.
-- [full comment]

[MattSturgeon]

Is it okay to link to other manuals from this one, or is each manual supposed to work offline

That'd be a question for the docs team, if it isn't documented in the docs READMEs.

IIRC there are already a few external links in the manual, but I could be wrong.

[jackrosenberg]

IIRC there are already a few external links in the manual, but I could be wrong.

Yea, a quick rg gives plenty of results

[Mindavi]

I'm pretty happy with this.

[Eveeifyeve]

I see no issues with this however @MattSturgeon might have some changes, so I would like to hear from them before merging if there is anything that is blocking this from merging.

[MattSturgeon]

LGTM on the whole. I've left some (a lot of) minor and/or subjective wording suggestions.

The most significant things for me are putting too much emphasis on env (implicitly discouraging use of structured shell variables) and whether we need a similar warning about passAsFile?

passAsFile usage is fairly common in Nixpkgs, and its conflict with __structuredAttrs isn't explicitly called out by the upstream nix docs, other than:

This obviates the need for passAsFile since JSON files have no size restrictions, unlike process environments.

If any specific point becomes contentions, I'm happy for it to be deferred to a future PR.

[jackrosenberg]

@MattSturgeon thanks for the in depth review! I'll take a look now :)

whether we need a similar warning about passAsFile?

sure, i don't see why not. it fits in nicely with the {.important} tag.

[MattSturgeon]

I think we can merge once https://github.com/NixOS/nixpkgs/pull/509970/changes#r3089058060 and the final nits are resolved, unless anyone has further feedback.*

*(Any significant feedback my be best as a follow-up PR, to reduce contributing friction)

[MattSturgeon]

Thanks for putting this together and sticking through the review process! LGTM

I'll merge this now, if anyone has further suggestions, improvements, nits, etc I'm happy to be pinged to review follow-up PRs.

[jackrosenberg]

Thanks for putting this together and sticking through the review process! LGTM

My pleasure, thanks for the quick responses!