lix-project/lix

Fork 54

[Nix#9701] `builtins.derivationStrict` is not documented #73

New issue

Open

opened 2024-03-16 06:44:46 +00:00 by lix-bot · 1 comment

lix-bot commented

2024-03-16 06:44:46 +00:00

Member

Upstream-Issue: NixOS/nix#9701

Problem

strictDerivation is not mentioned in the manual.

Should it be documented? Yes, because it is arguably a better function than derivation:

it is at least as capable as derivation
it doesn't return its arguments unnecessarily (blurring what's the actual interface of a package)
it's more efficient because it does less unnecessary attrset stuff
its returned attrNames are more predictable than those of derivation and (by extension) Nixpkgs mkDerivation,
- permitting more laziness when wrapped sensibly (not widely relevant, but even a couple percent of instantiations saved is a win)

Proposal

Document the derivation arguments on a separate page about derivations. This page is store-level documentation.
Document both builtins as usual, referring to the derivation page, and a paragraph about the return value and how it relates to the outputs argument.

Checklist

checked latest Nix manual (source)
checked open documentation issues and pull requests for possible duplicates

Priorities

Add 👍 to issues you find important.

Upstream-Issue: https://git.lix.systems/NixOS/nix/issues/9701 ## Problem `strictDerivation` is not mentioned in the manual. Should it be documented? Yes, because it is arguably a better function than `derivation`: - it is at least as capable as `derivation` - it doesn't return its arguments unnecessarily (blurring what's the actual interface of a package) - it's more efficient because it does less unnecessary attrset stuff - its returned `attrNames` are more predictable than those of `derivation` and (by extension) Nixpkgs `mkDerivation`, - _permitting_ more laziness when wrapped sensibly (not widely relevant, but even a couple percent of instantiations saved is a win) ## Proposal Document the derivation arguments on a separate page about derivations. This page is store-level documentation. Document both builtins as usual, referring to the derivation page, and a paragraph about the return value and how it relates to the `outputs` argument. ## Checklist  - [x] checked [latest Nix manual] \([source]) - [x] checked [open documentation issues and pull requests] for possible duplicates [latest Nix manual]: https://nixos.org/manual/nix/unstable/ [source]: https://github.com/NixOS/nix/tree/master/doc/manual/src [open documentation issues and pull requests]: https://github.com/NixOS/nix/labels/documentation ## Priorities Add :+1: to [issues you find important](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc).

lix-bot added the

imported

label

2024-03-16 06:44:46 +00:00

jade added the

docs

label

2024-03-18 16:24:33 +00:00

jade referenced this issue

2024-04-02 20:50:45 +00:00

Meta-bug: builtins.derivation replacement design #217

jade changed title from ~~[Nix#9701] builtins.strictDerivation~~ to [Nix#9701] builtins.derivationStrict

2024-04-14 21:26:51 +00:00

jade added this to the Docs rewrite project

2024-04-14 21:27:58 +00:00

jade added the

E/help wanted

label

2024-06-06 17:08:32 +00:00

qyriad changed title from ~~[Nix#9701] builtins.derivationStrict~~ to [Nix#9701] builtins.derivationStrict is not documented

2024-06-06 19:21:04 +00:00

lunaphied referenced this issue

2024-07-07 19:26:12 +00:00

builtins.derivation is not documented #436

lunaphied commented

2024-07-07 19:31:02 +00:00

Owner

I'm not entirely sure I agree with it being "more efficient", since builtins.derivation intentionally wraps builtins.derivationStrict lazy, using builtins.derivationStrict directly forces more to be done during initial eval. Though most uses would probably immediately wrap it again in a more comfortable interface like stdenv.mkDerivation anyway, so moving that step to downstream consumers is sensible.

However it should definitely be documented as it's what links eval to the actual creation of derivations in the store, i.e. it's one of our few impure operations (alongside builtins.toFile and the various builtins.fetch* operations.)

I'm not entirely sure I agree with it being "more efficient", since `builtins.derivation` intentionally wraps `builtins.derivationStrict` lazy, using `builtins.derivationStrict` directly forces more to be done during initial eval. Though most uses would probably immediately wrap it again in a more comfortable interface like `stdenv.mkDerivation` anyway, so moving that step to downstream consumers is sensible. However it should definitely be documented as it's what links eval to the actual creation of derivations in the store, i.e. it's one of our few impure operations (alongside `builtins.toFile` and the various `builtins.fetch*` operations.)

lunaphied added the

E/easy

labels

2024-07-07 19:33:45 +00:00