From 9235ff1259bb9425c58ac3b3322ddf83e74a4255 Mon Sep 17 00:00:00 2001 From: Michael Peyton Jones Date: Wed, 9 Aug 2017 19:47:27 +0100 Subject: Overlays: allow overlays to be specified in a file --- doc/overlays.xml | 56 +++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 15 deletions(-) (limited to 'doc') diff --git a/doc/overlays.xml b/doc/overlays.xml index ad31b90299e7..cc0aef447d2d 100644 --- a/doc/overlays.xml +++ b/doc/overlays.xml @@ -17,42 +17,68 @@ if multiple layers override the same package.
Installing overlays -The list of overlays is determined as follows: +The list of overlays is determined as follows. + +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 ] }. + then that is used. - On a NixOS system the value of the nixpkgs.overlays option, if present, - is passed to the system Nixpkgs in this way. Note that this does not affect the overlays for - non-NixOS operations (e.g. nix-env), which are looked up independently. + This can be passed explicitly when importing nipxkgs, for example + import <nixpkgs> { overlays = [ overlay1 overlay2 ]; }. - Otherwise, if the Nix path entry <nixpkgs-overlays> exists and is a - directory, then the result is the set of overlays found in that directory, ordered lexicographically. + 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>. - Otherwise, if ~/.config/nixpkgs/overlays/ exists and is a directory, then - the result is the set of overlays found in that directory, ordered lexicographically. + 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. -For the second and third options, overlays are extracted from the given directory as files, -directories containing a default.nix, or symlinks to one of those. +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. -The last option provides a convenient way to install an overlay from a repository, -by cloning the overlay's repository and adding a symbolic link to it in -~/.config/nixpkgs/overlays/. +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.
-- cgit 1.4.1