From 5c30512e09c15ff9d5a214d75093eb368e83829c Mon Sep 17 00:00:00 2001 From: Alyssa Ross Date: Sat, 3 Aug 2024 11:18:53 +0200 Subject: [PATCH] doc/using/overrides: manage package option expectations We haven't been good at managing expectations about this, so let's tell people what level of support they can expect. I think the place people are most likely to see it is the place where they learn about overriding in the first place, so I've added it here. Co-authored-by: Valentin Gagarin --- doc/using/overrides.chapter.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/using/overrides.chapter.md b/doc/using/overrides.chapter.md index 8c6ed79076c2..27a042963dd6 100644 --- a/doc/using/overrides.chapter.md +++ b/doc/using/overrides.chapter.md @@ -40,6 +40,13 @@ import pkgs.path { overlays = [ (self: super: { In the first example, `pkgs.foo` is the result of a function call with some default arguments, usually a derivation. Using `pkgs.foo.override` will call the same function with the given new arguments. +Many packages, like the `foo` example above, provide package options with default values in their arguments, to facilitate overriding. +Because it's not usually feasible to test that packages build with all combinations of options, you might find that a package doesn't build if you override options to non-default values. + +Package maintainers are not expected to fix arbitrary combinations of options. +If you find that something doesn't work, please submit a fix, ideally with a regression test. +If you want to ensure that things keep working, consider [becoming a maintainer](https://github.com/NixOS/nixpkgs/tree/master/maintainers) for the package. + ## <pkg>.overrideAttrs {#sec-pkg-overrideAttrs} The function `overrideAttrs` allows overriding the attribute set passed to a `stdenv.mkDerivation` call, producing a new derivation based on the original one. This function is available on all derivations produced by the `stdenv.mkDerivation` function, which is most packages in the nixpkgs expression `pkgs`.