From a3ff11ee41c8dd9892bb272101133f72c821f41c Mon Sep 17 00:00:00 2001
From: Akira Komamura <akira.komamura@gmail.com>
Date: Sun, 6 Oct 2024 14:30:39 +0900
Subject: [PATCH 1/2] feat: Add a non-overlay API

---
 flake.nix              |  6 ++++--
 lib/default.nix        |  4 ++++
 pkgs/default.nix       | 18 +++++++++---------
 pkgs/emacs/default.nix |  2 +-
 pkgs/overlay.nix       | 19 +++++++++++++++++++
 5 files changed, 37 insertions(+), 12 deletions(-)
 create mode 100644 pkgs/overlay.nix

diff --git a/flake.nix b/flake.nix
index a59940d..e3def1b 100644
--- a/flake.nix
+++ b/flake.nix
@@ -4,10 +4,12 @@
   inputs.elisp-helpers.url = "github:emacs-twist/elisp-helpers";
 
   outputs = {...} @ inputs: {
-    # lib is experimental at present, so it may be removed in the future.
+    # The APIs under lib is unstable at present. It may undergo changes in the
+    # future.
     lib = import ./lib inputs;
+    # The overlay API is deprecated.
     overlays = {
-      default = import ./pkgs inputs;
+      default = import ./pkgs/overlay.nix inputs;
     };
     homeModules = {
       emacs-twist = ./modules/home-manager.nix;
diff --git a/lib/default.nix b/lib/default.nix
index 9b49b02..110b1d6 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -7,6 +7,7 @@ let
     split
     filter
     isString
+    removeAttrs
     ;
 in
 {
@@ -49,4 +50,7 @@ in
         inherit inputs pkgs;
       };
     };
+
+  # A non-overlay API that builds a configuration environment.
+  makeEnv = { pkgs, ... }@args: import ../pkgs { inherit inputs pkgs; } (removeAttrs args [ "pkgs" ]);
 }
diff --git a/pkgs/default.nix b/pkgs/default.nix
index f997e33..80ff7fd 100644
--- a/pkgs/default.nix
+++ b/pkgs/default.nix
@@ -1,11 +1,11 @@
-inputs: final: prev: let
+{ inputs, pkgs }:
+let
   lib = import ./build-support {
-    inherit inputs;
-    pkgs = prev;
+    inherit pkgs inputs;
   };
-in {
-  emacsTwist = lib.makeOverridable (import ./emacs {
-    inherit final lib;
-    pkgs = prev;
-  });
-}
+in
+lib.makeOverridable (
+  import ./emacs {
+    inherit lib pkgs;
+  }
+)
diff --git a/pkgs/emacs/default.nix b/pkgs/emacs/default.nix
index 0cd09af..9250b61 100644
--- a/pkgs/emacs/default.nix
+++ b/pkgs/emacs/default.nix
@@ -1,7 +1,7 @@
 {
   lib,
   pkgs,
-  final,
+  final ? pkgs
 }: {
   emacsPackage ? pkgs.emacs,
   lockDir,
diff --git a/pkgs/overlay.nix b/pkgs/overlay.nix
new file mode 100644
index 0000000..8a29a36
--- /dev/null
+++ b/pkgs/overlay.nix
@@ -0,0 +1,19 @@
+# This is a deprecated API which adds `emacsTwist` function to nixpkgs.
+# It is recommended to use the function provided under lib.
+inputs: final: prev:
+let
+  lib = import ./build-support {
+    inherit inputs;
+    pkgs = prev;
+  };
+in
+{
+  emacsTwist =
+    args:
+    lib.warn "The overlay API of twist is now deprecated." (
+      lib.makeOverridable (import ./emacs {
+        inherit final lib;
+        pkgs = prev;
+      }) args
+    );
+}

From 6cfc4a4d97dd7745485ad637d265afe72805412a Mon Sep 17 00:00:00 2001
From: Akira Komamura <akira.komamura@gmail.com>
Date: Sun, 6 Oct 2024 14:37:07 +0900
Subject: [PATCH 2/2] test: Update the tests on the new function API

---
 test/flake.nix         | 20 +++++++++++---------
 test/twist-minimal.nix | 10 +++++-----
 test/twist.nix         |  5 +++--
 3 files changed, 19 insertions(+), 16 deletions(-)

diff --git a/test/flake.nix b/test/flake.nix
index 94ae787..1f400af 100644
--- a/test/flake.nix
+++ b/test/flake.nix
@@ -50,7 +50,6 @@
             import nixpkgs {
               inherit system;
               overlays = [
-                inputs.twist.overlays.default
                 (final: prev: {
                   emacsPackage = emacs-ci.packages.${system}.emacs-snapshot;
                 })
@@ -58,6 +57,8 @@
             }
           )
         );
+
+      inherit (inputs.twist.lib) makeEnv;
     in
     {
       devShells = eachSystemPkgs (pkgs: {
@@ -69,22 +70,23 @@
       });
 
       packages = eachSystemPkgs (pkgs: {
-        emacs = pkgs.callPackage ./twist.nix {
-          inherit inputs;
+        emacs = makeEnv (import ./twist.nix {
+          inherit inputs pkgs;
           inherit (pkgs) emacsPackage;
-        };
+        });
 
         # With explicit buitlins
-        emacs-builtins = pkgs.callPackage ./twist.nix {
-          inherit inputs;
+        emacs-builtins = makeEnv (import ./twist.nix {
+          inherit inputs pkgs;
           inherit (pkgs) emacsPackage;
           initialLibraries = inputs.emacs-builtins.data.emacs-snapshot.libraries;
-        };
+        });
 
         # Another test path to build the whole derivation (not with --dry-run).
-        emacs-wrapper = pkgs.callPackage ./twist-minimal.nix {
+        emacs-wrapper = makeEnv (import ./twist-minimal.nix {
+          inherit pkgs;
           inherit (pkgs) emacsPackage;
-        };
+        });
 
         # This is an example of interactive Emacs session.
         # You can start Emacs by running `nix run .#emacs-interactive`.
diff --git a/test/twist-minimal.nix b/test/twist-minimal.nix
index 295d7fd..5f1b11a 100644
--- a/test/twist-minimal.nix
+++ b/test/twist-minimal.nix
@@ -1,10 +1,10 @@
 {
-  emacsTwist,
+  pkgs,
   emacsPackage,
 }:
-emacsTwist {
-  inherit emacsPackage;
-  initFiles = [];
+{
+  inherit pkgs emacsPackage;
+  initFiles = [ ];
   lockDir = ./lock;
-  registries = [];
+  registries = [ ];
 }
diff --git a/test/twist.nix b/test/twist.nix
index df28656..0b8a8b8 100644
--- a/test/twist.nix
+++ b/test/twist.nix
@@ -1,10 +1,11 @@
 {
-  emacsTwist,
+  pkgs,
   emacsPackage,
   inputs,
   initialLibraries ? null,
 }:
-emacsTwist {
+{
+  inherit pkgs;
   # Use nix-emacs-ci which is more lightweight than a regular build
   inherit emacsPackage;
   # In an actual configuration, you would use this: