support local overlays

Author: domenkozar

devenv/src/flake.tmpl.nix

@@ -60,7 +60,7 @@
               then devenvdefaultpath
               else throw (devenvdefaultpath + " file does not exist for input ${name}.");
           project = pkgs.lib.evalModules {
-            specialArgs = inputs // { inherit inputs pkgs; };
+            specialArgs = inputs // { inherit inputs; bootstrapPkgs = pkgs; };
             modules = [
               (inputs.devenv.modules + /top-level.nix)
               {

docs/.pages

@@ -21,6 +21,7 @@ nav:
       - Binary caching: binary-caching.md
       - Git hooks: git-hooks.md
       - Tests: tests.md
+      - Overlays: overlays.md
       - Outputs: outputs.md
       - Common patterns: common-patterns.md
     - Writing devenv.yaml:

docs/overlays.md

@@ -0,0 +1,113 @@
+# Overlays
+
+!!! info "New in version 1.4.2"
+
+Overlays in devenv allow you to modify or extend the default package set (`pkgs`) that devenv uses. This is useful when you need to:
+
+- Override existing packages to apply patches
+- Add new packages that aren't in the default set
+- Use custom builds of existing packages
+
+## Using overlays
+
+To add overlays to your devenv configuration, use the `overlays` option in your `devenv.nix` file:
+
+```nix
+{ pkgs, ... }:
+
+{
+  # List of overlays to apply to pkgs
+  overlays = [
+    # Each overlay is a function that takes two arguments: final and prev
+    (final: prev: {
+      # Override an existing package
+      hello = prev.hello.overrideAttrs (oldAttrs: {
+        patches = (oldAttrs.patches or []) ++ [ ./hello-fix.patch ];
+      });
+
+      # Add a custom package
+      my-custom-package = final.callPackage ./my-package.nix {};
+    })
+  ];
+
+  # Now you can use the modified or added packages
+  packages = [ pkgs.hello pkgs.my-custom-package ];
+}
+```
+
+## How overlays work
+
+Each overlay is a function that takes two arguments:
+- `final`: The final package set after all overlays are applied
+- `prev`: The package set as it existed before this overlay (but after previous overlays)
+
+The function should return an attrset containing the packages you want to add or modify. These will be merged into the final package set.
+
+## Common use cases
+
+### Patching existing packages
+
+```nix
+overlays = [
+  (final: prev: {
+    # Apply a patch to fix a bug
+    somePackage = prev.somePackage.overrideAttrs (oldAttrs: {
+      patches = (oldAttrs.patches or []) ++ [ ./my-fix.patch ];
+    });
+  })
+];
+```
+
+### Using a different version of a package
+
+```nix
+overlays = [
+  (final: prev: {
+    # Use a specific version of Node.js
+    nodejs = prev.nodejs-18_x;
+  })
+];
+```
+
+### Adding custom packages
+
+```nix
+overlays = [
+  (final: prev: {
+    # Add a package from a local derivation
+    my-tool = final.callPackage ./nix/my-tool.nix {};
+  })
+];
+```
+
+### Using packages from older nixpkgs
+
+First, add the extra input to your `devenv.yaml`:
+
+```yaml
+inputs:
+  nixpkgs:
+    url: github:cachix/devenv-nixpkgs/rolling
+  nixpkgs-unstable:
+    url: github:nixos/nixpkgs/nixpkgs-unstable
+```
+
+Then use it in your `devenv.nix`:
+
+```nix
+{ pkgs, inputs, ... }:
+
+{
+  overlays = [
+    (final: prev: {
+      # Use a package from nixpkgs-unstable
+      nodejs = (import inputs.nixpkgs-unstable {
+        system = prev.stdenv.system;
+      }).nodejs;
+    })
+  ];
+
+  # Now you can use these packages from your regular pkgs
+  languages.javascript.enable = true;
+}
+```

examples/overlays/devenv.nix

@@ -8,4 +8,16 @@
     # from subflake
     pkgs.hello2
   ];
+
+  overlays = [
+    (final: prev: {
+      hello = prev.hello.overrideAttrs (old: {
+        name = "hello-2.0.0";
+      });
+    })
+  ];
+
+  enterTest = ''
+    which hello | grep "2.0.0"
+  '';
 }

src/modules/top-level.nix

@@ -1,4 +1,4 @@
-{ config, pkgs, lib, ... }:
+{ config, pkgs, lib, bootstrapPkgs ? null, ... }:
 let
   types = lib.types;
   # Returns a list of all the entries in a folder
@@ -60,6 +60,21 @@ in
       default = "";
     };
 
+    overlays = lib.mkOption {
+      type = types.listOf (types.functionTo (types.functionTo types.attrs));
+      description = "List of overlays to apply to pkgs. Each overlay is a function that takes two arguments: final and prev. Supported by devenv 1.4.2 or newer.";
+      default = [ ];
+      example = lib.literalExpression ''
+        [
+          (final: prev: {
+            hello = prev.hello.overrideAttrs (oldAttrs: {
+              patches = (oldAttrs.patches or []) ++ [ ./hello-fix.patch ];
+            });
+          })
+        ]
+      '';
+    };
+
     packages = lib.mkOption {
       type = types.listOf types.package;
       description = "A list of packages to expose inside the developer environment. Search available packages using ``devenv search NAME``.";
@@ -243,6 +258,12 @@ in
           See https://devenv.sh/guides/using-with-flakes/ how to use it with flakes.
         '';
       }
+      {
+        assertion = config.devenv.flakesIntegration || config.overlays == [ ] || lib.versionAtLeast config.devenv.cliVersion "1.4.2";
+        message = ''
+          Using overlays requires devenv 1.4.2 or higher, while your current version is ${config.devenv.cliVersion}.
+        '';
+      }
     ];
     # use builtins.toPath to normalize path if root is "/" (container)
     devenv.state = builtins.toPath (config.devenv.dotfile + "/state");
@@ -312,6 +333,8 @@ in
     infoSections."env" = lib.mapAttrsToList (name: value: "${name}: ${toString value}") config.env;
     infoSections."packages" = builtins.map (package: package.name) (builtins.filter (package: !(builtins.elem package.name (builtins.attrNames config.scripts))) config.packages);
 
+    _module.args.pkgs = bootstrapPkgs.appendOverlays config.overlays;
+
     ci = [ config.shell ];
     ciDerivation = pkgs.runCommand "ci" { } "echo ${toString config.ci} > $out";
   };