From ba8b54fa4a91cd94e8c42095d4f82d4a93cd01d1 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Thu, 27 Sep 2018 18:21:26 +0200 Subject: [PATCH 1/4] Add Nixpkgs functions for adding overlays ad-hoc This is something that I have found useful in tests. In practice I recommend that people call Nixpkgs once for performance and simplicity. The inline documentation mentions this too. --- pkgs/top-level/stage.nix | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) 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. From 9b7654f6ff326a7e35b48ce3c54d7f8bb71d9a13 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 15 Oct 2018 13:47:36 +0200 Subject: [PATCH 2/4] nixpkgs docs: Point to pkgs.extend, pkgs.appendOverlays and improve override section --- doc/functions/overrides.xml | 15 +++++++++++++-- doc/overlays.xml | 8 +++++++- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml index 99e2a63631a7..30cc6f3f6b1d 100644 --- a/doc/functions/overrides.xml +++ b/doc/functions/overrides.xml @@ -6,8 +6,16 @@ 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 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.
@@ -25,6 +33,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..af1ab26b5e97 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -30,10 +30,16 @@ itself is given, then that is used. - This can be passed explicitly when importing nipxkgs, for example + 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. + From 3c2ae189c2af388812d82596770df74ac8f839ee Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Thu, 18 Oct 2018 14:01:06 +0200 Subject: [PATCH 3/4] doc: Improve overrides and overlays documentation --- doc/functions/overrides.xml | 9 +- doc/overlays.xml | 197 ++++++++++++++++++++---------------- 2 files changed, 114 insertions(+), 92 deletions(-) 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. + + + +
From a5c4642ddf03f792c29764c53725f9b04e06decd Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Fri, 19 Oct 2018 12:25:17 +0200 Subject: [PATCH 4/4] doc: Add link from overrides to overlays --- doc/functions/overrides.xml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml index 5532951d1a79..4ba861bd1a42 100644 --- a/doc/functions/overrides.xml +++ b/doc/functions/overrides.xml @@ -11,8 +11,9 @@ 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. + packages. Overlays, on the other + hand, can be used to combine the overridden packages across the entire + package set of Nixpkgs.