soopy.moe
1# Overlays
2overlays are useful when you want to refer to a package globally, or to fix a broken package locally.
3
4you might also want to use overlays when something hasn't made it into nixos-unstable or whatever you're on yet, but you
5desparately need said thing.
6
7the gist of overlays is as thus:
8
9> overlay is just `final: prev: {}` functions
10>
11> dumbed down idea is that you do `pkg = prev.pkg.override` and
12> refer to everything else from `final`
13>
14> idea is like final = prev // overlay(prev, final)
15>
16> (it's a recursive definition)
17
18(poorly made) example overlays can be found [here](https://github.com/soopyc/nixos-config/blob/master/overlays/discord-canary.nix)
19
20~~currently in-use and slightly better overlays can be found in this repo! head over to /overlays to see them.~~
21
22*note: replace `self: super:` with `final: prev:` for consistency*
23
24UPDATE: we don't really use overlays anymore. If you'd like an example, please reach out and we can add some here.
25
26*concept and quote content by @natsukagami*
27
28```admonish info
29If you write 3rd party nix modules, it is a bad idea to do overlays as the performance impact propagates to everyone
30in the stream. See [this article that talks about overlays](
31 https://zimbatm.com/notes/1000-instances-of-nixpkgs
32).
33```
34
35## Overlaying python packages
36In some situations a python package may be bugged. This might have been fixed upstream by Nixpkgs devs, but has not reached `nixos-unstable` or whatever.
37
38While overriding normal packages is relatively straightforward, doing so with python is most definitely not.
39
40We have done this recently with the help of [Scrumplex] (thank you!) because a package was broken on nixos-unstable. Someone made a fix and it was merged, but it has yet to make it to nixos-unstable. This was blocking our systems from building so we decided to just say sod it, we're doing this.
41
42Again, overriding simple packages that are not inside any package groups is wildly easier than this operation. Since not every package group is the same, this sample only focuses on Python because we only have experience with that.
43
44Copy-paste the new package definiton next to the place where you're defining the overlay. We will be referencing it as `./package.nix`.
45
46```nix
47final: prev: {
48 # this does not work because the package uses python3Packages. this is defining standalone package.
49 pyscard = prev.python3Packages.callPackage ./package.nix {};
50
51 python3 = prev.python3.override {
52 self = final.python3;
53
54 # to their credit we do have this thing here which was already great
55 packageOverrides = (final': prev': {
56 # we cannot use final'.pkgs.callPackage here because it's missing buildPythonModule or something.
57 pyscard = final.python3Packages.callPackage ./package.nix {
58 inherit (final.darwin.apple_sdk.frameworks) PCSC; # apple carp
59 };
60 });
61 };
62
63 # probably some `rec` carp
64 # IMPORTANT: you need this! this is needed to let nix know we want to use our overrided python3 package earlier.
65 # if you don't add this, you will still be building the old package like nothing changed at all.
66 # Yes, nix is this sad.
67 python3Packages = final.python3.pkgs;
68}
69```
70
71A full example is accessible [here](https://github.com/soopyc/gensokyo/tree/53fcb9bdeeede6e250c84a05ff8c6c1aca9b5fe6/global/overlays/temp/pyscard).
72
73[Scrumplex]: https://github.com/scrumplex