Last updated: 2018-02-13 13:49:32 +0000

Upstream URL: git clone


View repository

View issue tracker

Contents of follows

Custom Nix Packages

This directory provides user-specific overrides for the Nix package manager. By naming it <code>~/.nixpkgs</code>, it will be automatically loaded by Nix; you could also load it separately, e.g. via an <code>import</code>.


<ul> <li><code>release.nix</code> is used for testing and continuous integration. It can be ignored if you just want to <em>use</em> these packages.</li> <li><code>config.nix</code> is loaded by Nix automatically (if it's in <code>~/.nixpkgs</code>) and used as a source of configuration options. The most important for us is <code>packageOverrides</code> (described below). Other, less important options are loaded from <code>other.nix</code>.</li> <li><code>custom.nix</code> defines the <code>packageOverrides</code> value used by <code>config.nix</code>. It combines the definitions from all the top-level <code>*.nix</code> files in <code>custom/</code>: <ul> <li>Each <code>custom/foo.nix</code> file is imported.</li> <li>The resulting function is called with <code>self</code> and <code>super</code> package sets.</li> <li>The resulting attribute set is combined with those of the other files.</li> <li>This combination is used as the value of <code>packageOverrides</code>.</li> </ul></li> <li><code>custom/</code> is where we define the contents for <code>packageOverrides</code>. Each <code>custom/*.nix</code> file should provide a (curried) 2-argument function, which takes <code>self</code> (the overridden package set) as its first argument and <code>super</code> (the original package set) as its second argument. The function should return a set of name/value pairs which will be added to the contents of <code>packageOverrides</code>. The filenames in <code>custom/</code> aren't important, as long as they end in <code>.nix</code>.</li> <li><code>custom/local/*.nix</code> files define packages more like those in nixpkgs: as a function from a set of dependencies to a derivation. The <code>custom/local.nix</code> file will add these to the <code>packageOverrides</code>, using the filename (sans the <code>.nix</code> suffix) as the attribute name. Most packages should probably go here, unless you have a reason otherwise.</li> <li><code>custom/haskell/*.nix</code> define Haskell packages. Each package is named from its filename, and will appear in each Haskell package set (e.g. for different versions of GHC). This is arranged by <code>custom/haskell.nix</code>.</li> </ul>

Important values

<ul> <li><code>super</code> is the name we use for the regular, system-wide set of packages. Like all values in Nix, <code>super</code> cannot be altered; instead, we can provide <em>overrides</em>, which will be used as-well-as/in-place-of the contents of <code>super</code>.</li> <li><code>packageOverrides</code> is a function taking <code>super</code> as an argument. The result is a set of attributes which Nix will <em>add to</em> <code>super</code> for our user (replacing, in the case of overlaps), i.e. <code>self = super // packageOverrides super</code>. For this reason, the <code>packageOverrides</code> should only contain new or overridden packages; copying from <code>super</code> to <code>packageOverrides</code> serves no purpose other than invalidating the binary cache. Note that these attributes don't need to be "packages" per se, for example they might be helper functions which we want to make available globally.</li> <li><code>self</code> is the complete set of Nix packages, including our overrides. Thanks to laziness, we can use <code>self</code> to define some overrides in terms of others; although care should be taken to avoid circular dependencies (i.e. infinite loops).</li> </ul>