Add lixFromNixpkgs, document the module

This commit is contained in:
jade 2024-07-30 15:11:02 -07:00
parent 8d462dfd9d
commit 533223d8ee
3 changed files with 88 additions and 4 deletions

View file

@ -1,5 +1,76 @@
# Lix NixOS module
See the [beta guide][beta-guide] for details on how to use this:
See the [official installation guide][install-guide] for details on usage of
release versions.
[install-guide]: https://lix.systems/install/
See the [beta guide][beta-guide] for a setup guide on how to use HEAD:
[beta-guide]: https://wiki.lix.systems/link/1
## What does this do?
This is an overlay wrapped in a NixOS module that will replace CppNix with Lix
in nixpkgs. This is useful so that `nixos-rebuild`, `nix-direnv` and similar
will use Lix.
Optionally, it can build Lix from source.
## Versioning with Lix
The version of this overlay should match the major Lix version, *and* if
running HEAD, it should be the latest available version of the overlay.
Breaking changes to the overlay are shamelessly done on HEAD.
The version of Lix pinned in this flake's `flake.lock` is a version of Lix
that is expected to work, however if running HEAD, it can be assumed to work
with HEAD as well if both `lix-nixos-module` and `lix` are the latest version.
## Common pitfalls
Various flake frameworks such as flake-parts and snowfall (and possibly Colmena
in the future if they do a similar optimization) manage overlays separately
from NixOS, since they provide `pkgs` pre-imported to NixOS. This saves a
couple of seconds of evaluation time and resources, but it means that the NixOS
option `nixpkgs.overlays` **is completely ignored** on these frameworks.
If you are using such a framework, add `overlays.default` to the overlays list
for said framework.
## Flake structure and usage
The flake here has two inputs of note:
- `nixpkgs`, *which is unused for most people*. It is purely used for `checks`
in developing `lix-nixos-module` itself.
The installation instructions make it `follows` to make `flake.lock` less
confusing, but it is nonetheless unused.
- `lix`, which determines the version of Lix to do source builds for, if doing
source builds.
These are the most relevant outputs for most people:
- `nixosModules.lixFromNixpkgs` - uses Lix from nixpkgs and installs the
overlay to use Lix on a NixOS system. This is only useful for a stable
version of Lix, and cannot be used for running HEAD.
- `nixosModules.default` - uses Lix from source and installs the overlay to use
Lix on a NixOS system.
- `overlays.lixFromNixpkgs` - overlay to use Lix from nixpkgs in place of Nix.
- `overlays.default` - overlay to use Lix from source in place of Nix.
## Non-flake usage
Import `module.nix` or `overlay.nix` as desired, with the arguments `lix`
(derivation-like attribute set with the Lix sources, or `null` to use Lix from
nixpkgs) and `versionSuffix` (optional string).
It's desirable to also include a `versionSuffix` like the following while
building HEAD from source, to have `nix --version` include date and commit
information. To get such metadata, it depends on which pinning system is in
use, but `builtins.fetchGit` will provide the necessary metadata for the
following to work:
```
versionSuffix = "pre${builtins.substring 0 8 lix.lastModifiedDate}-${lix.shortRev or lix.dirtyShortRev}";
```

View file

@ -11,8 +11,21 @@
let versionSuffix = "pre${builtins.substring 0 8 lix.lastModifiedDate}-${lix.shortRev or lix.dirtyShortRev}";
in {
inherit inputs;
nixosModules.default = import ./module.nix { inherit lix versionSuffix; };
overlays.default = import ./overlay.nix { inherit lix versionSuffix; };
nixosModules = {
# Use a locally built Lix
default = import ./module.nix { inherit lix versionSuffix; };
# Use Lix from nixpkgs
lixFromNixpkgs = import ./module.nix { lix = null; };
};
overlays = {
# Use a locally built Lix
default = import ./overlay.nix { inherit lix versionSuffix; };
# Use Lix from nixpkgs
lixFromNixpkgs = import ./overlay.nix { lix = null; };
};
} // flake-utils.lib.eachDefaultSystem (system:
let
pkgs = import nixpkgs {

View file

@ -1,4 +1,4 @@
{ lix ? null, versionSuffix ? "" }:
{ lix, versionSuffix ? "" }:
{ pkgs, config, ... }:
{
nixpkgs.overlays = [ (import ./overlay.nix { inherit lix versionSuffix; }) ];