Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
- bump version in devenv/Cargo.toml
- `cargo build`
- bump version in package.nix
- git commit
- git tag
- git push --tags
- create a release on github
- bump version in devenv/Cargo.toml and package.nix

# Once nixpkgs has been updated

Expand Down
2 changes: 1 addition & 1 deletion devenv/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "devenv"
version = "1.4.1"
version = "1.4.2"
edition.workspace = true
license.workspace = true

Expand Down
2 changes: 1 addition & 1 deletion devenv/src/flake.tmpl.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand Down
1 change: 1 addition & 0 deletions docs/.pages
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
113 changes: 113 additions & 0 deletions docs/overlays.md
Original file line number Diff line number Diff line change
@@ -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;
}
```
36 changes: 36 additions & 0 deletions docs/reference/options.md
Original file line number Diff line number Diff line change
Expand Up @@ -42442,6 +42442,42 @@ outputOf (attribute set)



## overlays



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.



*Type:*
list of function that evaluates to a(n) function that evaluates to a(n) (attribute set)



*Default:*
` [ ] `



*Example:*

```
[
(final: prev: {
hello = prev.hello.overrideAttrs (oldAttrs: {
patches = (oldAttrs.patches or []) ++ [ ./hello-fix.patch ];
});
})
]

```

*Declared by:*
- [https://github.com/cachix/devenv/blob/main/src/modules/top-level.nix](https://github.com/cachix/devenv/blob/main/src/modules/top-level.nix)



## pre-commit


Expand Down
12 changes: 12 additions & 0 deletions examples/overlays/devenv.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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"
'';
}
2 changes: 1 addition & 1 deletion package.nix
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

rustPlatform.buildRustPackage {
pname = "devenv";
version = "1.4.1";
version = "1.4.2";

# WARN: building this from src/modules/tasks.nix fails.
# There is something being prepended to the path, hence the .*.
Expand Down
25 changes: 24 additions & 1 deletion src/modules/top-level.nix
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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``.";
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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";
};
Expand Down