Document what callPackage does and its preconditions

[nh2]

I just lost some time on a misunderstanding about callPackage.

I changed from x = callPackage ./myfile.nix {} with myfile.nix just a mkDerivation as top-level expression, to x = (callPackage ./mfile.nix {}).val and changing myfile.nix to contain { val = mkDerivation ... }.

When I did that all my stuff broke.

So it looks like callPackage expects not only its inputs of a certain form, but also its outputs. I couldn't find this explained anywhere.

The docs about callPackage (which are surprisingly here in the nix manual, and not in the nixpkgs manual where I would expect them), say

Nixpkgs has a convenience function callPackage that imports and calls a function, filling in any missing arguments by passing the corresponding attribute from the Nixpkgs set

which sugggests callPackage is just a convenient wrapper that fills in arguments to the given expression file, and that otherwise it would return the same values as if I called that expression manually.

So I think we should document that callPackage does more than only input filling and has expectations about the expression returned by the file.

[danbst]

Yeah, probably what you want is called callPackages.

[Rizary]

+1, I always confuse between callPackages and callPackage

[stale[bot]]

Thank you for your contributions.

This has been automatically marked as stale because it has had no activity for 180 days.

If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.

Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the related code and @ mention them in a comment.
2. Ask on the NixOS Discourse.
3. Ask on the #nixos channel on irc.freenode.net.

[toraritte]

Just documenting this as I got confused as well:

$ nix repl <nixpkgs>

nix-repl> callPackages
«lambda @ /nix/store/w..q-nixos-20.09.2624.1eff582e7ea/nixos/lib/customisation.nix:127:32»

nix-repl> callPackage    
«lambda @ /nix/store/w..q-nixos-20.09.2624.1eff582e7ea/nixos/lib/customisation.nix:117:31»

https://github.com/NixOS/nixpkgs/blob/a6218c058b3e994779147dd7286606c750be7d73/lib/customisation.nix#L96-L139

[stale[bot]]

I marked this as stale due to inactivity. → More info

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-10-22-documentation-team-meeting-notes-12-nixcon-edition/22689/1

[Qyriad]

The docs about callPackage (which are surprisingly here in the nix manual, and not in the nixpkgs manual where I would expect them)

Looks like it's not in the Nix manual anymore either, so as far as I can tell callPackage is just generally undocumented outside of source or things like Nix Pills.

[toraritte]

Having an unhealthy obsession trying to understand Nix basics from time to time, here are some notes regarding callPackage:

• summer of nix callPackage, a tool for the lazy

  Just found this looking up my notes - didn't even know that such a write-up existed. Have only been able to rush through it, but it looks like the most comprehensive treatise on the topic. Perhaps the corresponding pull request #41 in the Summer of Nix repo is worth a glance too.

• stackoverflow Where is callPackage defined in the Nixpkgs repo (or how to find Nix lambda definitions in general)? w

• nixos discourse Where is callPackage defined exactly? (part 2)

Tangential:

• stackoverflow Nix: what's the concrete difference between nixpkgs and nixpkgs.pkgs?

• stackoverflow nix - Why is functionArgs implemented twice? (i.e, as a primop and in lib)

• stackoverflow nixpkgs - How does Nix's "callPackage" call functions defined without an ellipsis?

[fricklerhandwerk]

Also related: https://github.com/NixOS/nix.dev/issues/651