diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml
index 021c4b41c360..1bd90d2a0c76 100644
--- a/doc/functions/overrides.xml
+++ b/doc/functions/overrides.xml
@@ -6,8 +6,14 @@
Sometimes one wants to override parts of nixpkgs, e.g.
- derivation attributes, the results of derivations or even the whole package
- set.
+ derivation attributes, the results of derivations.
+
+
+
+ These functions are used to make changes to packages, returning only single
+ packages. Overlays, on the other
+ hand, can be used to combine the overridden packages across the entire
+ package set of Nixpkgs.
@@ -25,6 +31,9 @@
Example usages:
pkgs.foo.override { arg1 = val1; arg2 = val2; ... }
+
import pkgs.path { overlays = [ (self: super: {
foo = super.foo.override { barSupport = true ; };
diff --git a/doc/overlays.xml b/doc/overlays.xml
index 2decf9febe80..90dd163072d3 100644
--- a/doc/overlays.xml
+++ b/doc/overlays.xml
@@ -17,91 +17,122 @@
Installing overlays
- The list of overlays is determined as follows.
+ The list of overlays can be set either explicitly in a Nix expression, or
+ through <nixpkgs-overlays> or user configuration
+ files.
-
- If the overlays argument is not provided explicitly, we
- look for overlays in a path. The path is determined as follows:
-
-
-
- First, if an overlays argument to the nixpkgs function
- itself is given, then that is used.
-
-
- This can be passed explicitly when importing nipxkgs, for example
- import <nixpkgs> { overlays = [ overlay1 overlay2 ];
- }.
-
-
-
-
- Otherwise, if the Nix path entry <nixpkgs-overlays>
- exists, we look for overlays at that path, as described below.
-
-
- See the section on NIX_PATH in the Nix manual for more
- details on how to set a value for
- <nixpkgs-overlays>.
-
-
-
-
- If one of ~/.config/nixpkgs/overlays.nix and
- ~/.config/nixpkgs/overlays/ exists, then we look for
- overlays at that path, as described below. It is an error if both exist.
-
-
-
-
+
+ Set overlays in NixOS or Nix expressions
-
- If we are looking for overlays at a path, then there are two cases:
-
-
-
- If the path is a file, then the file is imported as a Nix expression and
- used as the list of overlays.
-
-
-
-
- If the path is a directory, then we take the content of the directory,
- order it lexicographically, and attempt to interpret each as an overlay
- by:
-
-
-
- Importing the file, if it is a .nix file.
-
-
-
-
- Importing a top-level default.nix file, if it is
- a directory.
-
-
-
-
-
-
-
+
+ On a NixOS system the value of the nixpkgs.overlays
+ option, if present, is passed to the system Nixpkgs directly as an
+ argument. Note that this does not affect the overlays for non-NixOS
+ operations (e.g. nix-env), which are
+ looked up independently.
+
-
- On a NixOS system the value of the nixpkgs.overlays
- option, if present, is passed to the system Nixpkgs directly as an argument.
- Note that this does not affect the overlays for non-NixOS operations (e.g.
- nix-env), which are looked up independently.
-
+
+ The list of overlays can be passed explicitly when importing nixpkgs, for
+ example import <nixpkgs> { overlays = [ overlay1 overlay2 ];
+ }.
+
-
- The overlays.nix option therefore provides a convenient
- way to use the same overlays for a NixOS system configuration and user
- configuration: the same file can be used as
- overlays.nix and imported as the value of
- nixpkgs.overlays.
-
+
+ Further overlays can be added by calling the pkgs.extend
+ or pkgs.appendOverlays, although it is often preferable
+ to avoid these functions, because they recompute the Nixpkgs fixpoint,
+ which is somewhat expensive to do.
+
+
+
+
+ Install overlays via configuration lookup
+
+
+ The list of overlays is determined as follows.
+
+
+
+
+
+
+ First, if an
+ overlays
+ argument to the nixpkgs function itself is given, then that is
+ used and no path lookup will be performed.
+
+
+
+
+ Otherwise, if the Nix path entry
+ <nixpkgs-overlays> exists, we look for overlays at
+ that path, as described below.
+
+
+ See the section on NIX_PATH in the Nix manual for
+ more details on how to set a value for
+ <nixpkgs-overlays>.
+
+
+
+
+ If one of ~/.config/nixpkgs/overlays.nix and
+ ~/.config/nixpkgs/overlays/ exists, then we look
+ for overlays at that path, as described below. It is an error if both
+ exist.
+
+
+
+
+
+
+ If we are looking for overlays at a path, then there are two cases:
+
+
+
+ If the path is a file, then the file is imported as a Nix expression and
+ used as the list of overlays.
+
+
+
+
+ If the path is a directory, then we take the content of the directory,
+ order it lexicographically, and attempt to interpret each as an overlay
+ by:
+
+
+
+ Importing the file, if it is a .nix file.
+
+
+
+
+ Importing a top-level default.nix file, if it is
+ a directory.
+
+
+
+
+
+
+
+
+
+ Because overlays that are set in NixOS configuration do not affect
+ non-NixOS operations such as nix-env, the
+ overlays.nix option provides a convenient way to use
+ the same overlays for a NixOS system configuration and user configuration:
+ the same file can be used as overlays.nix and imported
+ as the value of nixpkgs.overlays.
+
+
+
+
diff --git a/pkgs/top-level/stage.nix b/pkgs/top-level/stage.nix
index d0fb885dc747..37724a870a30 100644
--- a/pkgs/top-level/stage.nix
+++ b/pkgs/top-level/stage.nix
@@ -56,7 +56,7 @@
, # A list of overlays (Additional `self: super: { .. }` customization
# functions) to be fixed together in the produced package set
overlays
-}:
+} @args:
let
stdenvAdapters = self: super:
@@ -159,6 +159,19 @@ let
};
};
};
+
+ # Extend the package set with zero or more overlays. This preserves
+ # preexisting overlays. Prefer to initialize with the right overlays
+ # in one go when calling Nixpkgs, for performance and simplicity.
+ appendOverlays = extraOverlays:
+ import ./stage.nix (args // { overlays = args.overlays ++ extraOverlays; });
+
+ # Extend the package set with a single overlay. This preserves
+ # preexisting overlays. Prefer to initialize with the right overlays
+ # in one go when calling Nixpkgs, for performance and simplicity.
+ # Prefer appendOverlays if used repeatedly.
+ extend = f: self.appendOverlays [f];
+
};
# The complete chain of package set builders, applied from top to bottom.