diff --git a/doc/overlays.xml b/doc/overlays.xml index 4ad2764f33f..c921289fd6c 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -4,56 +4,53 @@ Overlays -This chapter describes how to extend and change Nixpkgs content using -overlays. Overlays are used to add layers in the fix-point used by Nixpkgs -to bind the dependencies of all packages. +This chapter describes how to extend and change Nixpkgs packages using +overlays. Overlays are used to add layers in the fix-point used by Nixpkgs +to compose the set of all packages.
Installing Overlays -The set of overlays are looked for in the following order, only the +The set of overlays is looked for in the following places. The first one present is considered, and all the rest are ignored: - As argument of the imported attribute set. When importing Nixpkgs, + As an argument of the imported attribute set. When importing Nixpkgs, the overlays attribute argument can be set to a list of - functions, which would be describe in . + functions, which is described in . - As a directory pointed by the environment variable named -NIXPKGS_OVERLAYS. This directory can contain symbolic -links to Nix expressions. - + In the directory pointed by the environment variable +NIXPKGS_OVERLAYS. - As the directory located at -~/.nixpkgs/overlays/. This directory can contain -symbolic links to Nix expressions. - + In the directory ~/.nixpkgs/overlays/. -For the second and third option, the directory contains either -directories providing a default.nix expression, or files, or symbolic links -to the entry Nix expression of the overlay. These Nix expressions are -following the syntax described in . +For the second and third option, the directory should contain Nix expressions defining the +overlays. Each overlay can be a file, a directory containing a +default.nix, or a symlink to one of those. The expressions should follow +the syntax described in . -To install an overlay, using the last option. Clone the repository of -the overlay, and add a symbolic link to it in the -~/.nixpkgs/overlays/ directory. +The order of the overlay layers can influence the recipe of packages if multiple layers override +the same recipe. In the case where overlays are loaded from a directory, these are loaded in +alphabetical order. + +To install an overlay using the last option, you can clone the overlay's repository and add +a symbolic link to in the ~/.nixpkgs/overlays/ directory.
@@ -62,37 +59,40 @@ the overlay, and add a symbolic link to it in the
Overlays Layout -An overlay is a Nix expression, which is a function which accepts 2 -arguments. +Overlays are expressed as Nix functions which accept 2 arguments and return a set of +packages self: super: { - foo = super.foo.override { ... }; - bar = import ./pkgs/bar { - inherit (self) stdenv fetchurl; - inherit (self) ninja crawl dwarf-fortress; + boost = super.boost.override { + python = self.python3; + }; + rr = super.callPackage ./pkgs/rr { + stdenv = self.stdenv_32bit; }; } -The first argument, usualy named self, corresponds -to the final package set. You should use this set to inherit all the -dependencies needed by your package expression. +The first argument, usually named self, corresponds to the final package +set. You should use this set for the dependencies of all packages specified in your +overlay. For example, all the dependencies of rr in the example above come +from self, as well as the overriden dependencies used in the +boost override. -The second argument, usualy named super, +The second argument, usually named super, corresponds to the result of the evaluation of the previous stages of -Nixpkgs, it does not contain any of the packages added by the current -overlay nor any of the following overlays. This set is used in to override -existing packages, either by changing their dependencies or their -recipes. +Nixpkgs. It does not contain any of the packages added by the current +overlay nor any of the following overlays. This set should be used either +to refer to packages you wish to override, or to access functions defined +in Nixpkgs. For example, the original recipe of boost +in the above example, comes from super, as well as the +callPackage function. The value returned by this function should be a set similar to -pkgs/top-level/all-packages.nix, which contains either -extra packages defined by the overlay, or which overwrite Nixpkgs packages -with other custom defaults. This is similar to . +pkgs/top-level/all-packages.nix, which contains +overridden and/or new packages.
diff --git a/nixos/doc/manual/release-notes/rl-1703.xml b/nixos/doc/manual/release-notes/rl-1703.xml index d6b3aeb9791..099fb05c8b4 100644 --- a/nixos/doc/manual/release-notes/rl-1703.xml +++ b/nixos/doc/manual/release-notes/rl-1703.xml @@ -113,7 +113,7 @@ following incompatible changes: pkgs.overridePackages (self: super: ...) - Should be replaced by: + should be replaced by: let diff --git a/nixos/modules/misc/nixpkgs.nix b/nixos/modules/misc/nixpkgs.nix index 885d56216ed..296a9b4badf 100644 --- a/nixos/modules/misc/nixpkgs.nix +++ b/nixos/modules/misc/nixpkgs.nix @@ -69,7 +69,7 @@ in openssh = super.openssh.override { hpnSupport = true; withKerberos = true; - kerberos = self.libkrb5 + kerberos = self.libkrb5; }; }; ) ]