Overview of package customisation

[zmitchell]

Project description

It's very common to want to tweak a particular feature of an existing package. For example, you may want a package compiled with different options. You may want this modified package used just for your build, or you may want this modified package used throughout the entire dependency tree. There's a variety of mechanisms available that are appropriate in different contexts.

• Overlays
• overrideAttrs
• Modifying derivation phase scripts
• Applying patches
• Any others?

This tutorial could take a package from Nixpkgs and try to modify one of its dependencies. The tutorial should show how to achieve the same modification (where possible or reasonable) using different mechanisms, clearly illustrating the tradeoffs or when one mechanism makes more sense over another.

Steps

• Submit a PR with a draft of the tutorial
  • Only work on this for about an hour before submitting something.
  • It's good to get early feedback so that you don't spend time on a tutorial that's going in a less than ideal direction.

Considerations

It will probably be difficult, if not impossible, to find one modification that can be made using all of the mechanisms listed above. In that situation I would prefer that multiple modifications be used as examples rather than try to use override mechanisms that don't make sense.

[TLATER]

Sounds like this is where #678 is going :)

[zmitchell]

That's true but we have a tracking issue specifically for tutorials :)

[zmitchell]

@infinisil and @roberth we need some input on how to proceed with this one:

• Which of these methods is best used in which situations?
• Are there any caveats or things to avoid with any of these methods?

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-10-05-documentation-team-meeting-notes-84/33877/1

[infinisil]

There's only two main ways of overriding generic packages:

• For all packages declared using stdenv.mkDerivation { ... }, .overrideAttrs allows overriding the attributes passed in the mkDerivation argument.
  So this means things like phases, patches, source, env vars, etc.
• For all packages declared using pkgs.callPackage ({ foo, withFoo ? false }: ...) { } (where the first argument could be a file too), .override can be used to override the attribute arguments passed to the first argument (by default callPackage fills out the arguments with pkgs). So the exact arguments that you can override depend on the package definition, but there's two general categories:
  • Dependencies like stdenv, libfoo, curl, etc. Generally these arguments don't have a default specified and so are defaulted to the values from pkgs
  • Configuration flags like withGui, enableFoo, etc. Generally these arguments do have a default specified and so are not defaulted to the values from pkgs

This is still fairly comprehensible but then we get into the more intricate ones..

---

There's the config argument to nixpkgs (which really just passes it on to pkgs.config), but this is a way to have configure many packages the same way, e.g. config.cudaSupport, which packages like blender or mathematica use.

Furthermore there are some more specific ways to override packages like .overridePythonAttrs or overrideCabal

And then you get to ways of overriding package sets, including:

• Nixpkgs top-level overlays (overlays argument, appendOverlays, pkgs.extend)
• Nested package set overlays (.overrideScope, .extend, pythonPackagesExtensions, ...)

And probably like 10 other ways of overriding various ways of Nixpkgs I'm forgetting. Generally you need to look at the source to figure out how to override something non-standard.

This entire situation sucks big time, and it's in scope for the Nixpkgs Architecture Team to improve. This was previously attempted but had to be put on hold due to resource constraints.