Merge commit 'f76e870d64779109e41370848074ac4eaa1606ec' into HEAD

ChangeLog.md

@@ -1,3 +1,26 @@
+
+# 2023-05-30
+
+ - Fix a strictness issue in `perInput`, affecting `inputs'`, `self'`.
+   This has caused infinite recursions and potentially performance issues since
+   the introduction of these module arguments.
+
+# 2023-05-08
+
+ - Add [`importApply`](https://flake.parts/define-module-in-separate-file.html?highlight=importApply#importApply) for bringing variables from the flake scope into module files.
+
+ - Add `mkDeferredModuleOption` as a generic name for the implementation of `mkPerSystemOption`.
+
+# 2023-03-26
+
+ - Add preliminary support for `disabledModules` for modules exposed via the importable `flakeModules` module.
+   This requires a Nixpkgs of 2023-03-09 or newer.
+
+# 2023-01-05
+
+ - Add importable `easyOverlay` module for defining an overlay "easily" by reusing `perSystem`.
+   This is not for consuming overlays.
+
 # 2022-12-25
 
  - Added a new `flake.flakeModules` option so a flake can expose a module

README.md

@@ -3,12 +3,18 @@
 
 _Core of a distributed framework for writing Nix Flakes._
 
-`flake-parts` provides the options that represent standard flake attributes 
+`flake-parts` provides the options that represent standard flake attributes
 and establishes a way of working with `system`.
 Opinionated features are provided by an ecosystem of modules that you can import.
 
 `flake-parts` _itself_ has the goal to be a minimal mirror of the Nix flake schema.
-Used by itself, it is very lightweight. 
+Used by itself, it is very lightweight.
+
+---
+
+**Documentation**: [flake.parts](https://flake.parts)
+
+---
 
 # Why Modules?
 
@@ -71,14 +77,22 @@ then slide `mkFlake` between your outputs function head and body,
 
 Now you can add the remaining module attributes like in the [the template](./template/default/flake.nix).
 
-# Example
+# Templates
 
 See [the template](./template/default/flake.nix).
 
+# Examples
+
+See the [examples/](./examples) directory.
+
+# Projects using flake-parts
+
+- [nixd](https://github.com/nix-community/nixd/blob/main/flake.nix) (c++)
+- [hyperswitch](https://github.com/juspay/hyperswitch/blob/main/flake.nix) (rust)
+- [argo-workflows](https://github.com/argoproj/argo-workflows/blob/master/dev/nix/flake.nix) (go)
+- [nlp-service](https://github.com/recap-utr/nlp-service/blob/main/flake.nix) (python)
+- [emanote](https://github.com/srid/emanote/blob/master/flake.nix) (haskell)
+
 # Options Reference
 
 See [flake.parts options](https://flake.parts/options/flake-parts.html)
-
-# Documentation
-
-See [flake.parts](https://flake.parts)

all-modules.nix

@@ -1,4 +1,3 @@
-{ lib, ... }:
 {
   imports = [
     ./modules/apps.nix

dev/flake-module.nix

@@ -13,7 +13,7 @@
     when.dayOfMonth = 1;
   };
 
-  perSystem = { config, self', inputs', pkgs, ... }: {
+  perSystem = { config, pkgs, ... }: {
 
     devShells.default = pkgs.mkShell {
       nativeBuildInputs = [
@@ -42,7 +42,7 @@
     # for repl exploration / debug
     config.config = config;
     options.mySystem = lib.mkOption { default = config.allSystems.${builtins.currentSystem}; };
-    config.effects = withSystem "x86_64-linux" ({ config, pkgs, hci-effects, ... }: {
+    config.effects = withSystem "x86_64-linux" ({ pkgs, hci-effects, ... }: {
       tests = {
         template = pkgs.callPackage ./tests/template.nix { inherit hci-effects; };
       };

dev/flake.nix

@@ -12,7 +12,7 @@
     hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";
   };
 
-  outputs = { self, ... }:
+  outputs = { ... }:
     {
       # The dev tooling is in ./flake-module.nix
       # See comment at `inputs` above.

dev/tests/eval-tests.nix

@@ -26,6 +26,22 @@ rec {
       systems = [ ];
     };
 
+  emptyExposeArgs = mkFlake
+    { inputs.self = { outPath = "the self outpath"; }; }
+    ({ config, moduleLocation, ... }: {
+      flake = {
+        inherit moduleLocation;
+      };
+    });
+
+  emptyExposeArgsNoSelf = mkFlake
+    { inputs.self = throw "self won't be available in case of some errors"; }
+    ({ config, moduleLocation, ... }: {
+      flake = {
+        inherit moduleLocation;
+      };
+    });
+
   example1 = mkFlake
     { inputs.self = { }; }
     {
@@ -35,6 +51,18 @@ rec {
       };
     };
 
+  packagesNonStrictInDevShells = mkFlake
+    { inputs.self = packagesNonStrictInDevShells; /* approximation */ }
+    {
+      systems = [ "a" "b" ];
+      perSystem = { system, self', ... }: {
+        packages.hello = pkg system "hello";
+        packages.default = self'.packages.hello;
+        devShells = throw "can't be strict in perSystem.devShells!";
+      };
+      flake.devShells = throw "can't be strict in devShells!";
+    };
+
   easyOverlay = mkFlake
     { inputs.self = { }; }
     {
@@ -148,6 +176,10 @@ rec {
 
     assert flakeModulesDisable.test123 == "option123";
 
+    assert packagesNonStrictInDevShells.packages.a.default == pkg "a" "hello";
+
+    assert emptyExposeArgs.moduleLocation == "the self outpath/flake.nix";
+
     ok;
 
   result = runTests "ok";

examples/project-commands/Hello.avdl

@@ -0,0 +1,6 @@
+protocol Hello {
+    record Hello {
+        string message;
+        int timestamp;
+    }
+}

examples/project-commands/README.md

@@ -0,0 +1,42 @@
+# project-commands
+
+> **Warning**
+> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
+
+This example shows how to create scripts for your project, by leveraging [mission-control](https://github.com/Platonic-Systems/mission-control)
+
+This is a **potential** alternative to:
+
+- Using a `Makefile` to manage your project's scripts
+- Using the popular [Scripts To Rule Them All](https://github.com/github/scripts-to-rule-them-all); a naming convention for a `scripts/` directory
+- Using a `bin/` directory
+
+## Explanation
+
+In this example we use the [avro-tools](https://avro.apache.org/) to convert our scripts from `.avdl` to `.avsc`.
+
+You don't need to know anything about avro to understand mission-control and use this example (that's Nix baby 🚀).
+
+When setting up [mission-control](https://github.com/Platonic-Systems/mission-control), we add
+one script called `build`. Because of `wrapperName = "run";`, once we open the shell created by nix,
+the commands will be listed as `run build`.
+
+mission-control depends on flake-root, which also exposes the helpful `$FLAKE_ROOT` variable.
+
+After creating the scripts, we need to pass the newly created scripts to the desired shell, in this example we use the default shell.
+
+## Usage
+
+Run:
+
+```sh
+nix develop
+```
+
+And mission-control will print in the new shell the available commands (you should see only one).
+
+Try running
+
+```sh
+run build
+```

examples/project-commands/flake.lock

@@ -0,0 +1,95 @@
+{
+  "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1685662779,
+        "narHash": "sha256-cKDDciXGpMEjP1n6HlzKinN0H+oLmNpgeCTzYnsA2po=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "71fb97f0d875fd4de4994dfb849f2c75e17eb6c3",
+        "type": "github"
+      },
+      "original": {
+        "id": "flake-parts",
+        "type": "indirect"
+      }
+    },
+    "flake-root": {
+      "locked": {
+        "lastModified": 1680964220,
+        "narHash": "sha256-dIdTYcf+KW9a4pKHsEbddvLVSfR1yiAJynzg2x0nfWg=",
+        "owner": "srid",
+        "repo": "flake-root",
+        "rev": "f1c0b93d05bdbea6c011136ba1a135c80c5b326c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "srid",
+        "repo": "flake-root",
+        "type": "github"
+      }
+    },
+    "mission-control": {
+      "locked": {
+        "lastModified": 1683658484,
+        "narHash": "sha256-JkGnWyYZxOnyOhztrxLSqaod6+O/3rRypq0dAqA/zn0=",
+        "owner": "Platonic-Systems",
+        "repo": "mission-control",
+        "rev": "a0c93bd764a3c25e6999397e9f5f119c1b124e38",
+        "type": "github"
+      },
+      "original": {
+        "owner": "Platonic-Systems",
+        "repo": "mission-control",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1687502512,
+        "narHash": "sha256-dBL/01TayOSZYxtY4cMXuNCBk8UMLoqRZA+94xiFpJA=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "3ae20aa58a6c0d1ca95c9b11f59a2d12eebc511f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "dir": "lib",
+        "lastModified": 1685564631,
+        "narHash": "sha256-8ywr3AkblY4++3lIVxmrWZFzac7+f32ZEhH/A8pNscI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4f53efe34b3a8877ac923b9350c874e3dcd5dc0a",
+        "type": "github"
+      },
+      "original": {
+        "dir": "lib",
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "flake-root": "flake-root",
+        "mission-control": "mission-control",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

examples/project-commands/flake.nix

@@ -0,0 +1,37 @@
+{
+  description = "Description for the project";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    mission-control.url = "github:Platonic-Systems/mission-control";
+    flake-root.url = "github:srid/flake-root";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+        inputs.mission-control.flakeModule
+        inputs.flake-root.flakeModule
+      ];
+      systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" ];
+      perSystem = { config, self', inputs', pkgs, system, ... }: {
+        devShells.default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ avro-tools ];
+          inputsFrom = [ config.mission-control.devShell config.flake-root.devShell ];
+        };
+        mission-control = {
+          wrapperName = "run";
+          scripts = {
+            build = {
+              description = "convert files from .avdl to .avsc";
+              exec = ''
+                avro-tools idl2schemata "$FLAKE_ROOT/Hello.avdl" .
+              '';
+              category = "Development";
+            };
+          };
+        };
+      };
+    };
+}

examples/shell-environments/README.md

@@ -0,0 +1,55 @@
+# shell-environment
+
+> **Warning**
+> If you copy the flake.nix remember to `git add [-N|--intent-to-add] flake.nix`, otherwise it won't work
+
+This example shows how to create a shell environment which
+includes a diverse set of tools:
+
+```sh
+terraform
+wget
+bat
+nixpkgs-fmt
+```
+
+You can search for more packages in [nix packages](https://search.nixos.org/packages)
+
+## Usage
+
+The [`devShells` option](https://flake.parts/options/flake-parts.html#opt-perSystem.devShells) is used by the following command:
+
+```sh
+nix develop
+```
+
+You can have as many shells as you want, in this [flake.nix](./flake.nix), you also have
+`another_env` which includes `curl`. To open it:
+
+```sh
+nix develop .#another_env
+```
+
+## Troubleshooting
+
+### I get bash instead of my shell
+
+`nix develop` was designed for Nixpkgs stdenv, which uses bash, so that you can troubleshoot a Nix build with it. If you use a different shell, you'll want to get just the variables instead.
+
+There are 3 possible solutions:
+
+First, using [direnv](https://direnv.net/) to manage your dev environments. See [direnv-guide](https://haskell.flake.page/direnv). This is the recommended approach.
+
+Second is a simple-unreliable hack, which is adding a `shellHook` to `devShells`
+
+```nix
+devShells.default = pkgs.mkShell {
+  shellHook = ''
+    exec $SHELL
+  '';
+};
+```
+
+You might get a lot different issues, use it at your own risk.
+
+Lastly, there's `nix print-dev-env` which returns the variables - in case you're feeling adventurous, because this is far from a complete solution. See `nix print-dev-env --help`.

examples/shell-environments/flake.lock

@@ -0,0 +1,63 @@
+{
+  "nodes": {
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1685662779,
+        "narHash": "sha256-cKDDciXGpMEjP1n6HlzKinN0H+oLmNpgeCTzYnsA2po=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "71fb97f0d875fd4de4994dfb849f2c75e17eb6c3",
+        "type": "github"
+      },
+      "original": {
+        "id": "flake-parts",
+        "type": "indirect"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1687412861,
+        "narHash": "sha256-Z/g0wbL68C+mSGerYS2quv9FXQ1RRP082cAC0Bh4vcs=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "e603dc5f061ca1d8a19b3ede6a8cf9c9fcba6cdc",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "dir": "lib",
+        "lastModified": 1685564631,
+        "narHash": "sha256-8ywr3AkblY4++3lIVxmrWZFzac7+f32ZEhH/A8pNscI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "4f53efe34b3a8877ac923b9350c874e3dcd5dc0a",
+        "type": "github"
+      },
+      "original": {
+        "dir": "lib",
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

examples/shell-environments/flake.nix

@@ -0,0 +1,22 @@
+{
+  description = "Description for the project";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [ "x86_64-linux" "aarch64-darwin" "x86_64-darwin" ];
+      perSystem = { config, self', inputs', pkgs, system, ... }: {
+        devShells.default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ terraform wget bat nixpkgs-fmt ];
+        };
+
+        devShells.another_env = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ curl ];
+        };
+      };
+
+    };
+}

extras/easyOverlay.nix

@@ -1,4 +1,4 @@
-toplevel@{ config, lib, flake-parts-lib, getSystemIgnoreWarning, ... }:
+toplevel@{ lib, flake-parts-lib, getSystemIgnoreWarning, ... }:
 let
   inherit (flake-parts-lib)
     mkPerSystemOption;
@@ -37,7 +37,7 @@ in
         };
       };
       config = {
-        _module.args.final = lib.mkDefault (pkgs.extend (toplevel.config.flake.overlays.default));
+        _module.args.final = lib.mkDefault (pkgs.extend toplevel.config.flake.overlays.default);
       };
     });
   };

extras/flakeModules.nix

@@ -1,10 +1,8 @@
-{ config, self, lib, flake-parts-lib, moduleLocation, ... }:
+{ self, lib, flake-parts-lib, moduleLocation, ... }:
 let
   inherit (lib)
-    filterAttrs
     mapAttrs
     mkOption
-    optionalAttrs
     types
     ;
   inherit (flake-parts-lib)

flake.lock

@@ -3,11 +3,11 @@
     "nixpkgs-lib": {
       "locked": {
         "dir": "lib",
-        "lastModified": 1682879489,
-        "narHash": "sha256-sASwo8gBt7JDnOOstnps90K1wxmVfyhsTPPNTGBPjjg=",
+        "lastModified": 1696019113,
+        "narHash": "sha256-X3+DKYWJm93DRSdC5M6K5hLqzSya9BjibtBsuARoPco=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "da45bf6ec7bbcc5d1e14d3795c025199f28e0de0",
+        "rev": "f5892ddac112a1e9b3612c39af1b72987ee5783a",
         "type": "github"
       },
       "original": {

flake.nix

@@ -5,8 +5,15 @@
     nixpkgs-lib.url = "github:NixOS/nixpkgs/nixos-unstable?dir=lib";
   };
 
-  outputs = { self, nixpkgs-lib, ... }: {
-    lib = import ./lib.nix { inherit (nixpkgs-lib) lib; };
+  outputs = { nixpkgs-lib, ... }: {
+    lib = import ./lib.nix {
+      inherit (nixpkgs-lib) lib;
+      # Extra info for version check message
+      revInfo =
+        if nixpkgs-lib?rev
+        then " (nixpkgs-lib.rev: ${nixpkgs-lib.rev})"
+        else "";
+    };
     templates = {
       default = {
         path = ./template/default;

lib.nix

@@ -1,4 +1,8 @@
-{ lib }:
+{ lib
+  # Optionally a string with extra version info to be included in the error message
+  # in case is lib is out of date. Empty or starts with space.
+, revInfo ? ""
+}:
 let
   inherit (lib)
     mkOption
@@ -28,27 +32,6 @@ let
     then maybeFlake._type == "flake"
     else maybeFlake ? inputs && maybeFlake ? outputs && maybeFlake ? sourceInfo;
 
-  # Polyfill functionTo to make sure it has type merging.
-  # Remove 2022-12
-  functionTo =
-    let sample = types.functionTo lib.types.str;
-    in
-    if sample.functor.wrapped._type or null == "option-type"
-    then types.functionTo
-    else
-      elemType: lib.mkOptionType {
-        name = "functionTo";
-        description = "function that evaluates to a(n) ${elemType.description}";
-        check = lib.isFunction;
-        merge = loc: defs:
-          fnArgs: (lib.mergeDefinitions (loc ++ [ "[function body]" ]) elemType (map (fn: { inherit (fn) file; value = fn.value fnArgs; }) defs)).mergedValue;
-        getSubOptions = prefix: elemType.getSubOptions (prefix ++ [ "[function body]" ]);
-        getSubModules = elemType.getSubModules;
-        substSubModules = m: functionTo (elemType.substSubModules m);
-        functor = (lib.defaultFunctor "functionTo") // { type = functionTo; wrapped = elemType; };
-        nestedTypes.elemType = elemType;
-      };
-
   # Polyfill https://github.com/NixOS/nixpkgs/pull/163617
   deferredModuleWith = lib.deferredModuleWith or (
     attrs@{ staticModules ? [ ] }: mkOptionType {
@@ -100,6 +83,21 @@ let
         '')
       , moduleLocation ? "${self.outPath}/flake.nix"
       }:
+      let
+        inputsPos = builtins.unsafeGetAttrPos "inputs" args;
+        errorLocation =
+          # Best case: user makes it explicit
+          args.moduleLocation or (
+            # Slightly worse: Nix does not technically commit to unsafeGetAttrPos semantics
+            if inputsPos != null
+            then inputsPos.file
+            # Slightly worse: self may not be valid when an error occurs
+            else if args?inputs.self.outPath
+            then args.inputs.self.outPath + "/flake.nix"
+            # Fallback
+            else "<mkFlake argument>"
+          );
+      in
       throwIf
         (!args?self && !args?inputs) ''
         When invoking flake-parts, you must pass in the flake output arguments.
@@ -121,7 +119,7 @@ let
             inherit self flake-parts-lib moduleLocation;
             inputs = args.inputs or /* legacy, warned above */ self.inputs;
           } // specialArgs;
-          modules = [ ./all-modules.nix module ];
+          modules = [ ./all-modules.nix (lib.setDefaultModuleLocation errorLocation module) ];
         }
         );
 
@@ -138,14 +136,7 @@ let
 
     mkFlake = args: module:
       let
-        loc =
-          args.moduleLocation or (
-            if args?inputs.self.outPath
-            then args.inputs.self.outPath + "/flake.nix"
-            else "<mkFlake argument>"
-          );
-        mod = lib.setDefaultModuleLocation loc module;
-        eval = flake-parts-lib.evalFlakeModule args mod;
+        eval = flake-parts-lib.evalFlakeModule args module;
       in
       eval.config.flake;
 
@@ -219,7 +210,7 @@ let
           } // optionalAttrs (toType != null) {
           type = toType;
         });
-        config = (mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt);
+        config = mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt;
       };
 
     # Helper function for importing while preserving module location. To be added
@@ -231,5 +222,19 @@ let
       lib.setDefaultModuleLocation modulePath (import modulePath staticArgs);
   };
 
+  # A best effort, lenient estimate. Please use a recent nixpkgs lib if you
+  # override it at all.
+  minVersion = "22.05";
+
 in
-flake-parts-lib
+
+if builtins.compareVersions lib.version minVersion < 0
+then
+  abort ''
+    The nixpkgs-lib dependency of flake-parts was overridden but is too old.
+    The minimum supported version of nixpkgs-lib is ${minVersion},
+    but the actual version is ${lib.version}${revInfo}.
+  ''
+else
+
+  flake-parts-lib

modules/apps.nix

@@ -1,4 +1,4 @@
-{ config, lib, flake-parts-lib, ... }:
+{ lib, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption
@@ -17,11 +17,6 @@ let
   getExe = x:
     "${lib.getBin x}/bin/${x.meta.mainProgram or (throw ''Package ${x.name or ""} does not have meta.mainProgram set, so I don't know how to find the main executable. You can set meta.mainProgram, or pass the full path to executable, e.g. program = "''${pkg}/bin/foo"'')}";
 
-  getBin = x:
-    if !x?outputSpecified || !x.outputSpecified
-    then x.bin or x.out or x
-    else x;
-
   appType = lib.types.submodule {
     options = {
       type = mkOption {

modules/checks.nix

@@ -1,4 +1,4 @@
-{ config, lib, flake-parts-lib, ... }:
+{ lib, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption

modules/debug.nix

@@ -10,9 +10,6 @@ let
   inherit (flake-parts-lib)
     mkPerSystemOption
     ;
-  inherit (builtins)
-    removeAttrs
-    ;
 
   mkDebugConfig = { config, options, extendModules }: config // {
     inherit config;

modules/devShells.nix

@@ -1,8 +1,9 @@
-{ config, lib, flake-parts-lib, ... }:
+{ lib, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption
     types
+    literalExpression
     ;
   inherit (flake-parts-lib)
     mkTransposedPerSystemModule
@@ -17,6 +18,13 @@ mkTransposedPerSystemModule {
       An attribute set of packages to be used as shells.
       [`nix develop .#<name>`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html) will run `devShells.<name>`.
     '';
+    example = literalExpression ''
+      {
+        default = pkgs.mkShell {
+          nativeBuildInputs = with pkgs; [ wget bat cargo ];
+        };
+      }
+    '';
   };
   file = ./devShells.nix;
 }

modules/flake.nix

@@ -1,10 +1,7 @@
-{ config, lib, ... }:
+{ lib, ... }:
 let
   inherit (lib)
-    filterAttrs
-    mapAttrs
     mkOption
-    optionalAttrs
     types
     ;
 in

modules/formatter.nix

@@ -24,7 +24,7 @@ in
       };
     };
 
-    perSystem = mkPerSystemOption ({ config, ... }: {
+    perSystem = mkPerSystemOption {
       _file = ./formatter.nix;
       options = {
         formatter = mkOption {
@@ -35,7 +35,7 @@ in
           '';
         };
       };
-    });
+    };
   };
   config = {
     flake.formatter =

modules/legacyPackages.nix

@@ -1,4 +1,4 @@
-{ config, lib, flake-parts-lib, ... }:
+{ lib, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption

modules/moduleWithSystem.nix

@@ -1,4 +1,4 @@
-{ config, lib, withSystem, ... }:
+{ withSystem, ... }:
 {
   config = {
     _module.args = {

modules/nixosConfigurations.nix

@@ -1,4 +1,4 @@
-{ config, lib, flake-parts-lib, ... }:
+{ lib, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption

modules/nixosModules.nix

@@ -1,10 +1,8 @@
-{ config, self, lib, flake-parts-lib, moduleLocation, ... }:
+{ self, lib, flake-parts-lib, moduleLocation, ... }:
 let
   inherit (lib)
-    filterAttrs
     mapAttrs
     mkOption
-    optionalAttrs
     types
     ;
   inherit (flake-parts-lib)

modules/overlays.nix

@@ -1,4 +1,4 @@
-{ config, lib, flake-parts-lib, ... }:
+{ lib, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption
@@ -16,7 +16,7 @@ in
         # also update description when done
         type = types.lazyAttrsOf (types.uniq (types.functionTo (types.functionTo (types.lazyAttrsOf types.unspecified))));
         # This eta expansion exists for the sole purpose of making nix flake check happy.
-        apply = lib.mapAttrs (k: f: final: prev: f final prev);
+        apply = lib.mapAttrs (_k: f: final: prev: f final prev);
         default = { };
         example = lib.literalExpression or lib.literalExample ''
           {

modules/packages.nix

@@ -1,4 +1,4 @@
-{ config, lib, flake-parts-lib, ... }:
+{ lib, flake-parts-lib, ... }:
 let
   inherit (lib)
     mkOption

modules/transposition.nix

@@ -7,10 +7,6 @@ let
     mkOption
     types
     ;
-  inherit (flake-parts-lib)
-    mkSubmoduleOptions
-    mkPerSystemOption
-    ;
 
   transpositionModule = {
     options = {
@@ -35,6 +31,13 @@ in
       description = ''
         A helper that defines transposed attributes in the flake outputs.
 
+        When you define `transposition.foo = { };`, definitions are added to the effect of (pseudo-code):
+
+        ```nix
+        flake.foo.''${system} = (perSystem system).foo;
+        perInput = system: inputFlake: inputFlake.foo.''${system};
+        ```
+
         Transposition is the operation that swaps the indices of a data structure.
         Here it refers specifically to the transposition between
 
@@ -65,12 +68,9 @@ in
       system: flake:
       mapAttrs
         (attrName: attrConfig: flake.${attrName}.${system})
-        (filterAttrs
-          (attrName: attrConfig: flake?${attrName}.${system})
-          config.transposition
-        );
+        config.transposition;
 
-    perSystem = { ... }: {
+    perSystem = {
       options =
         mapAttrs
           (k: v: lib.mkOption { })

modules/withSystem.nix

@@ -1,8 +1,6 @@
-{ config, lib, flake-parts-lib, self, getSystem, ... }:
+{ lib, flake-parts-lib, getSystem, ... }:
 let
   inherit (lib)
-    genAttrs
-    mapAttrs
     mkOption
     types
     ;
@@ -12,7 +10,7 @@ let
 in
 {
   options = {
-    perSystem = mkPerSystemOption ({ config, options, system, specialArgs, ... }: {
+    perSystem = mkPerSystemOption ({ config, options, specialArgs, ... }: {
       _file = ./perSystem.nix;
       options = {
         allModuleArgs = mkOption {

template/default/flake.nix

@@ -14,7 +14,7 @@
         # 3. Add here: foo.flakeModule
 
       ];
-      systems = [ "x86_64-linux" "aarch64-darwin" ];
+      systems = [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" "x86_64-darwin" ];
       perSystem = { config, self', inputs', pkgs, system, ... }: {
         # Per-system attributes can be defined here. The self' and inputs'
         # module parameters provide easy access to attributes of the same

template/package/flake.nix

@@ -0,0 +1,21 @@
+{
+  description = "Description for the project";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = [ "x86_64-linux" "aarch64-linux" "aarch64-darwin" "x86_64-darwin" ];
+      perSystem = { config, pkgs, ... }: {
+        packages.default = config.packages.hello;
+
+        packages.hello = pkgs.callPackage ./hello/package.nix { };
+
+        checks.hello = pkgs.callPackage ./hello/test.nix {
+          hello = config.packages.hello;
+        };
+      };
+    };
+}

template/package/hello/hello.sh

@@ -0,0 +1,3 @@
+#!@shell@
+
+echo Hello world

template/package/hello/package.nix

@@ -0,0 +1,22 @@
+{ stdenv, lib, runtimeShell }:
+
+# Example package in the style that `mkDerivation`-based packages in Nixpkgs are written.
+stdenv.mkDerivation (finalAttrs: {
+  name = "hello";
+  src = lib.cleanSourceWith {
+    src = ./.;
+    filter = path: type:
+      type == "regular" -> baseNameOf path == "hello.sh";
+  };
+  buildPhase = ''
+    # Note that Nixpkgs has builder functions for simple packages
+    # like this, but this template avoids it to make for a more
+    # complete example.
+    substitute hello.sh hello --replace '@shell@' ${runtimeShell}
+    cat hello
+    chmod a+x hello
+  '';
+  installPhase = ''
+    install -D hello $out/bin/hello
+  '';
+})

template/package/hello/test.nix

@@ -0,0 +1,12 @@
+{ hello, runCommand }:
+
+runCommand "test-hello"
+{
+  inherit hello;
+} '' 
+  (
+    set -x
+    [[ "Hello world" == "$(${hello}/bin/hello)" ]]
+  )
+  touch $out
+''