Add a non-overlay API for defining a config

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;

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" ]);
 }

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;
+  }
+)

pkgs/emacs/default.nix

@@ -1,7 +1,7 @@
 {
   lib,
   pkgs,
-  final,
+  final ? pkgs
 }: {
   emacsPackage ? pkgs.emacs,
   lockDir,

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
+    );
+}

test/flake.nix

@@ -50,14 +50,15 @@
             import nixpkgs {
               inherit system;
               overlays = [
-                inputs.twist.overlays.default
                 (final: prev: {
                   emacsPackage = emacs-ci.packages.${system}.emacs-snapshot;
                 })
               ];
             }
           )
         );
+
+      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`.

test/twist-minimal.nix

@@ -1,10 +1,10 @@
 {
-  emacsTwist,
+  pkgs,
   emacsPackage,
 }:
-emacsTwist {
-  inherit emacsPackage;
-  initFiles = [];
+{
+  inherit pkgs emacsPackage;
+  initFiles = [ ];
   lockDir = ./lock;
-  registries = [];
+  registries = [ ];
 }

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: