From 533223d8eeb8c6d3f25a276b02c770a47594e5be Mon Sep 17 00:00:00 2001
From: Jade Lovelace <lix@jade.fyi>
Date: Tue, 30 Jul 2024 15:11:02 -0700
Subject: [PATCH] Add lixFromNixpkgs, document the module

---
 README.md  | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 flake.nix  | 17 +++++++++++--
 module.nix |  2 +-
 3 files changed, 88 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index c86dc5c..af8975d 100644
--- a/README.md
+++ b/README.md
@@ -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}";
+```
diff --git a/flake.nix b/flake.nix
index b7b412a..ec4c53f 100644
--- a/flake.nix
+++ b/flake.nix
@@ -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 {
diff --git a/module.nix b/module.nix
index dcc7f01..5e7f1bf 100644
--- a/module.nix
+++ b/module.nix
@@ -1,4 +1,4 @@
-{ lix ? null, versionSuffix ? "" }:
+{ lix, versionSuffix ? "" }:
 { pkgs, config, ... }:
 {
   nixpkgs.overlays = [ (import ./overlay.nix { inherit lix versionSuffix; }) ];