Skip to content

lib.customisation: Functions to customise (derivation-related) functions, derivatons, or attribute sets

lib.customisation.overrideDerivation

overrideDerivation drv f takes a derivation (i.e., the result of a call to the builtin function derivation) and returns a new derivation in which the attributes of the original are overridden according to the function f. The function f is called with the original derivation attributes.

overrideDerivation allows certain "ad-hoc" customisation scenarios (e.g. in ~/.config/nixpkgs/config.nix). For instance, if you want to "patch" the derivation returned by a package function in Nixpkgs to build another version than what the function itself provides.

For another application, see build-support/vm, where this function is used to build arbitrary derivations inside a QEMU virtual machine.

Note that in order to preserve evaluation errors, the new derivation's outPath depends on the old one's, which means that this function cannot be used in circular situations when the old derivation also depends on the new one.

You should in general prefer drv.overrideAttrs over this function; see the nixpkgs manual for more information on overriding.

Inputs

drv

: 1. Function argument

f

: 2. Function argument

Type

overrideDerivation :: Derivation -> ( Derivation -> AttrSet ) -> Derivation

Examples

lib.customisation.overrideDerivation usage example

mySed = overrideDerivation pkgs.gnused (oldAttrs: {
  name = "sed-4.2.2-pre";
  src = fetchurl {
    url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;
    hash = "sha256-MxBJRcM2rYzQYwJ5XKxhXTQByvSg5jZc5cSHEZoB2IY=";
  };
  patches = [];
});

Located at lib/customisation.nix:77 in <nixpkgs>.

lib.customisation.makeOverridable

makeOverridable takes a function from attribute set to attribute set and injects override attribute which can be used to override arguments of the function.

Please refer to documentation on <pkg>.overrideDerivation to learn about overrideDerivation and caveats related to its use.

Inputs

f

: 1. Function argument

Type

makeOverridable :: (AttrSet -> a) -> AttrSet -> a

Examples

lib.customisation.makeOverridable usage example

nix-repl> x = {a, b}: { result = a + b; }

nix-repl> y = lib.makeOverridable x { a = 1; b = 2; }

nix-repl> y
{ override = «lambda»; overrideDerivation = «lambda»; result = 3; }

nix-repl> y.override { a = 10; }
{ override = «lambda»; overrideDerivation = «lambda»; result = 12; }

Located at lib/customisation.nix:131 in <nixpkgs>.

lib.customisation.callPackageWith

Call the package function in the file fn with the required arguments automatically. The function is called with the arguments args, but any missing arguments are obtained from autoArgs. This function is intended to be partially parameterised, e.g.,

callPackage = callPackageWith pkgs;
pkgs = {
  libfoo = callPackage ./foo.nix { };
  libbar = callPackage ./bar.nix { };
};

If the libbar function expects an argument named libfoo, it is automatically passed as an argument. Overrides or missing arguments can be supplied in args, e.g.

libbar = callPackage ./bar.nix {
  libfoo = null;
  enableX11 = true;
};

Inputs

autoArgs

: 1. Function argument

fn

: 2. Function argument

args

: 3. Function argument

Type

callPackageWith :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a

Located at lib/customisation.nix:212 in <nixpkgs>.

lib.customisation.callPackagesWith

Like callPackage, but for a function that returns an attribute set of derivations. The override function is added to the individual attributes.

Inputs

autoArgs

: 1. Function argument

fn

: 2. Function argument

args

: 3. Function argument

Type

callPackagesWith :: AttrSet -> ((AttrSet -> AttrSet) | Path) -> AttrSet -> AttrSet

Located at lib/customisation.nix:298 in <nixpkgs>.

lib.customisation.extendDerivation

Add attributes to each output of a derivation without changing the derivation itself and check a given condition when evaluating.

Inputs

condition

: 1. Function argument

passthru

: 2. Function argument

drv

: 3. Function argument

Type

extendDerivation :: Bool -> Any -> Derivation -> Derivation

Located at lib/customisation.nix:339 in <nixpkgs>.

lib.customisation.hydraJob

Strip a derivation of all non-essential attributes, returning only those needed by hydra-eval-jobs. Also strictly evaluate the result to ensure that there are no thunks kept alive to prevent garbage collection.

Inputs

drv

: 1. Function argument

Type

hydraJob :: (Derivation | Null) -> (Derivation | Null)

Located at lib/customisation.nix:388 in <nixpkgs>.

lib.customisation.makeScope

Make an attribute set (a "scope") from functions that take arguments from that same attribute set. See for how to use it.

Inputs

  1. newScope (AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a)

A function that takes an attribute set attrs and returns what ends up as callPackage in the output.

Typical values are callPackageWith or the output attribute newScope.

  1. f (AttrSet -> AttrSet)

A function that takes an attribute set as returned by makeScope newScope f (a "scope") and returns any attribute set.

This function is used to compute the fixpoint of the resulting scope using callPackage. Its argument is the lazily evaluated reference to the value of that fixpoint, and is typically called self or final.

See for how to use it. See for details on fixpoint computation.

Output

makeScope returns an attribute set of a form called scope, which also contains the final attributes produced by f:

scope :: {
  callPackage :: ((AttrSet -> a) | Path) -> AttrSet -> a
  newScope = AttrSet -> scope
  overrideScope = (scope -> scope -> AttrSet) -> scope
  packages :: AttrSet -> AttrSet
}
  • callPackage (((AttrSet -> a) | Path) -> AttrSet -> a)

A function that

  1. Takes a function p, or a path to a Nix file that contains a function p, which takes an attribute set and returns value of arbitrary type a,
  2. Takes an attribute set args with explicit attributes to pass to p,
  3. Calls f with attributes from the original attribute set attrs passed to newScope updated with args, i.e.attrs // args, if they match the attributes in the argument ofp`.

All such functions p will be called with the same value for attrs.

See for how to use it.

  • newScope (AttrSet -> scope)

Takes an attribute set attrs and returns a scope that extends the original scope.

  • overrideScope ((scope -> scope -> AttrSet) -> scope)

Takes a function g of the form final: prev: { # attributes } to act as an overlay on f, and returns a new scope with values determined by extends g f. See for details.

This allows subsequent modification of the final attribute set in a consistent way, i.e. all functions p invoked with callPackage will be called with the modified values.

  • packages (AttrSet -> AttrSet)

The value of the argument f to makeScope.

  • final attributes

The final values returned by f.

Examples

{#ex-makeScope .example}

Create an interdependent package set on top of pkgs

The functions in foo.nix and bar.nix can depend on each other, in the sense that foo.nix can contain a function that expects bar as an attribute in its argument.

let
  pkgs = import <nixpkgs> { };
in
pkgs.lib.makeScope pkgs.newScope (self: {
  foo = self.callPackage ./foo.nix { };
  bar = self.callPackage ./bar.nix { };
})

evaluates to

{
  callPackage = «lambda»;
  newScope = «lambda»;
  overrideScope = «lambda»;
  packages = «lambda»;
  foo = «derivation»;
  bar = «derivation»;
}

{#ex-makeScope-callPackage .example}

Using callPackage from a scope

let
  pkgs = import <nixpkgs> { };
  inherit (pkgs) lib;
  scope = lib.makeScope lib.callPackageWith (self: { a = 1; b = 2; });
  three = scope.callPackage ({ a, b }: a + b) { };
  four = scope.callPackage ({ a, b }: a + b) { a = 2; };
in
[ three four ]

evaluates to

[ 3 4 ]

Type

makeScope :: (AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a) -> (AttrSet -> AttrSet) -> scope

Located at lib/customisation.nix:541 in <nixpkgs>.

lib.customisation.makeScopeWithSplicing

backward compatibility with old uncurried form; deprecated

Inputs

splicePackages

: 1. Function argument

newScope

: 2. Function argument

otherSplices

: 3. Function argument

keep

: 4. Function argument

extra

: 5. Function argument

f

: 6. Function argument

Located at lib/customisation.nix:584 in <nixpkgs>.

lib.customisation.makeScopeWithSplicing'

Like makeScope, but aims to support cross compilation. It's still ugly, but hopefully it helps a little bit.

Type

makeScopeWithSplicing' ::
  { splicePackages :: Splice -> AttrSet
  , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a
  }
  -> { otherSplices :: Splice, keep :: AttrSet -> AttrSet, extra :: AttrSet -> AttrSet }
  -> AttrSet

Splice ::
  { pkgsBuildBuild :: AttrSet
  , pkgsBuildHost :: AttrSet
  , pkgsBuildTarget :: AttrSet
  , pkgsHostHost :: AttrSet
  , pkgsHostTarget :: AttrSet
  , pkgsTargetTarget :: AttrSet
  }

Located at lib/customisation.nix:614 in <nixpkgs>.