diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml
index 30cc6f3f6b1d..5532951d1a79 100644
--- a/doc/functions/overrides.xml
+++ b/doc/functions/overrides.xml
@@ -10,12 +10,9 @@
- These overriding functions let you focus on one part of Nixpkgs and give you
- back the requested variation. This is orthogonal but related to overlays and
- the extending functions. Those also let you make modifications but return the
- whole package set instead of just what you modified. When used together, the
- override functions make the changes and overlays or extending functions add
- those changes to the package sets.
+ 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.
diff --git a/doc/overlays.xml b/doc/overlays.xml
index af1ab26b5e97..90dd163072d3 100644
--- a/doc/overlays.xml
+++ b/doc/overlays.xml
@@ -17,97 +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 nixpkgs, for example
- import <nixpkgs> { overlays = [ overlay1 overlay2 ];
- }.
-
-
- 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.
-
-
-
-
- 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.
+
+
+
+