Post History

<sup>For the record, this write-up is **not** better than any of the resources listed in the question; writing it simply helped me better understand `callPackage`.</sup>

### Level 0. Poor, but short

`callPackage f attr_set` will

+ call function `f` with inputs automatically supplied from `attr_set` and [Nixpkgs][1]
+ make the resulting [attribute set][2] overridable.

`callPackage` is used overwhelmingly with functions that produce a derivation. Building a project can require a lot of dependencies that won't have to be specified manually this way, and `callPackage` also makes it possible to configure "Nix derivation expressions" after `callPackage` has been called using [overrides][3]. ([This email][4] goes has the full rationale.)

<sup>"_Nix derivation expression_" is just a personal term, not an official one, that I use to refer to an [attribute set][2] that represents a [store derivation][5] in terms of the Nix language before [instantiation][6]. </sup>

### Level 1. Wordier and still inexact

`callPackage` accepts 2 inputs:

1. a **function** that takes as input an [attribute set][2]  
   <sup>e.g., `{ stdenv, miez, lofa ? 27 }: { inherit stdenv miez lofa; }`</sup>

2. an **[attribute set][2]** that must be a subset of the input function's input attribute set  
   <sup>e.g., in the case of the example in item 1., this would be ok: `{ miez = 7; lofa = 9; }`</sup>

`callPackage` will

1. call the input function with an [attribute set][2] whose attributes are supplied from

   + the [attribute set][2] in `callPackage`'s 2<sup>nd</sup> argument
   + a subset of the [Nixpkgs][1] package (attribute) set<sup><b>1</b></sup>

2. make the resulting [attribute set][2] overridable. 

### Level 2. More precise but also more abstruse

```
callPackage ::    ( attr_set_function | path_to_file_with_attr_set_function )
               -> constrained_attr_set
               -> ( overridable_attr_set | arbitrary_nix_value )

attr_set_function :: input_attr_set -> attr_set
```
<sup><b>The Nix language is [dynamically typed][7], so this is just a personal notation.</b></sup>

where

+ `input_attr_set` is a regular [attribute set][2] with caveats depending on whether its attributes are [Nixpkgs][1] or not:

  + **IN [Nixpkgs][1]**  
    If the attribute names match attributes in the limited subset of [Nixpkgs][1] package set<sup><b>1</b></sup>, then these won't have to be specified in `constrained_attr_set` as `callPackage` will auto-populate them.

  + **NOT in [Nixpkgs][1]**  
    These either must have a default value or have to be specified in `constrained_attr_set`.

+ `constrained_attr_set` is an [attribute set][2] that can only be a subset of `attr_set_function`'s input [attribute set][2].

+ `overridable_att_set` - See [this section][3] of the `nix.dev` tutorial.

### Level 3. Source

https://github.com/NixOS/nixpkgs/blame/e7f2456df49b39e816e9ed71622c09a42446a581/pkgs/top-level/splice.nix#L125-L144

```
  splicedPackagesWithXorg = splicedPackages // builtins.removeAttrs splicedPackages.xorg [
    "callPackage"
    "newScope"
    "overrideScope"
    "packages"
  ];

  # ...

  callPackage = pkgs.newScope { };
  callPackages = ...;
  newScope = extra: lib.callPackageWith (splicedPackagesWithXorg // extra);
```
<sup>`callPackages` (note the extra `s`!) is also defined here, but omitted it, lest I muddy the waters even more.</sup>

[`callPackageWith`][8] is quite long and the resources in the question explain the nitty-gritty, but the gist is this line:

```nix
callPackage = f: args:
  f ((builtins.intersectAttrs (builtins.functionArgs f) pkgs) // args);
```
<sup> ... and [this is an email from 2009][4] that introduces it.</sup>


### Examples

> NOTE  
> The term `pkgs` below will refer to the [Nixpkgs][1] package set. Such as the result of any of the following calls in [`nix repl`][9]:
>
> * `pkgs = import `[`<nixpkgs>`](https://stackoverflow.com/q/47379654/1498178)` {}`
> * `pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/06278c77b5d162e62df170fec307e83f1812d94b.tar.gz") {}`
> * ... and so on

* ✅ 
  ```
  pkgs.callPackage ({ lib, stdenv }: { ... }) {}
  ```  
  `lib` and `stdenv` are valid attributes in [Nixpkgs][1], so these will be auto-populated from there. Roughly equivalent to:  
  `pkgs.callPackage ({ lib, stdenv }: ... }) { lib = pkgs.lib; stdenv = pkgs.stdenv; }`

* ✅ 
  ```
  pkgs.callPackage ({ lib, stdenv, lofa ? 27 }: { ... }) {}
  ```  
  Same things apply as in the previous item, except that [Nixpkgs][1] has no `lofa` attribute, but there is a default value provided for it, so it will work.

* ✅ 
  ```
  ( pkgs.callPackage 
      ({ lib, stdenv, lofa }: { inherit lofa lib; })
      { lofa = 27; lib = "whatever"; }
  )
  ```  
  Same as in previous item, but attributes `lofa` and `lib` are explicitly provided.

* ✅
  ```
   let
     id = x: x;
   in
     pkgs.callPackage id {}
  ```
  `callPackage`'s input function (1st parameter) is called with an [attribute set][2], so this still works.

* ❌ 
  ```
  pkgs.callPackage (i: i + 2) {}
  ```  
  `callPackage` will choke because `i` will be an [attribute set][2] and the `+` operator will try to coerce it into a string.

* ❌ 
  ```
  pkgs.callPackage ({ lib, stdenv, lofa }: { inherit lofa; }) {}
  ```  
  will raise `error: Function called without required argument "lofa"`.

* ✅ 
  ```
  $ echo "{lib, stdenv, lofa ? 27}: {inherit lofa;}" > f.nix
  
  $ nix repl
  
  nix-repl> pkgs = import <nixpkgs> {}
  nix-repl> pkgs.callPackage ./f.nix {}
  ```  
  Providing a valid file system path containing a Nix expression (that conforms to what `callPackage` is accepting) works too as the file will be automatically imported first.


The result of `attr_set_function` is usually a Nix derivation expression (which is an attribute set denoting a derivation - or something like it; look this up).

---

\[1]: https://github.com/NixOS/nixpkgs/blame/e7f2456df49b39e816e9ed71622c09a42446a581/pkgs/top-level/splice.nix#L140-L144


  [1]: https://nix.dev/reference/glossary#term-Nixpkgs
  [2]: https://nix.dev/manual/nix/stable/language/values#attribute-set
  [3]: https://nix.dev/tutorials/callpackage#overrides
  [4]: https://www.mail-archive.com/nix-dev@cs.uu.nl/msg02624.html
  [5]: https://nix.dev/manual/nix/2.22/glossary#gloss-store-derivation
  [6]: https://nix.dev/manual/nix/2.22/glossary#gloss-instantiate
  [7]: https://nix.dev/tutorials/nix-language.html
  [8]: https://github.com/NixOS/nixpkgs/blob/7370c67890fb6ae18bad28496a684294ec1b3f88/lib/customisation.nix#L212-L269
  [9]: https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-repl