Merge pull request #9 from hercules-ci/docs-and-ci

Docs and initial ci

ci.nix

@@ -0,0 +1,12 @@
+# We're doing things a bit differently because Nix doesn't let us
+# split out the dev dependencies and subflakes are broken, let alone "superflakes".
+# See dev/README.md
+let
+  flake = import ./dev;
+  inherit (flake.inputs.nixpkgs) lib;
+in
+{
+  inherit (flake) herculesCI;
+} // {
+  checks = lib.recurseIntoAttrs flake.checks.${builtins.currentSystem};
+}

dev/README.md

@@ -0,0 +1,6 @@
+
+# Separate `tools` flake
+
+Wouldn't recommend this pattern normally, but I'm trying to keep
+deps low for `flake-modules-core` until we have split dev inputs
+that don't carry over to dependent lock files.

dev/default.nix

@@ -0,0 +1,12 @@
+let
+  flake = builtins.getFlake (toString ./.);
+  fmc-lib = import ../lib.nix { inherit (flake.inputs.nixpkgs) lib; };
+  self = {
+    inherit (flake) inputs;
+    outPath = ../.; # used by pre-commit module, etc
+  } //
+  fmc-lib.evalFlakeModule
+    { inherit self; }
+    ./flake-module.nix;
+in
+self.config.flake // { inherit (flake) inputs; }

dev/flake-module.nix

@@ -0,0 +1,56 @@
+flakeModuleArgs@{ config, lib, inputs, ... }:
+
+{
+  imports = [
+    inputs.pre-commit-hooks-nix.flakeModule
+  ];
+  systems = [ "x86_64-linux" "aarch64-darwin" ];
+  perSystem = system: { config, self', inputs', pkgs, ... }: {
+    _module.args.pkgs = inputs'.nixpkgs.legacyPackages;
+
+    devShells.default = pkgs.mkShell {
+      nativeBuildInputs = [
+        pkgs.nixpkgs-fmt
+        pkgs.pre-commit
+      ];
+      shellHook = ''
+        ${config.pre-commit.installationScript}
+      '';
+    };
+    pre-commit = {
+      inherit pkgs; # should make this default to the one it can get via follows
+      settings = {
+        hooks.nixpkgs-fmt.enable = true;
+      };
+    };
+
+    packages = {
+      inherit (pkgs.nixosOptionsDoc { inherit (flakeModuleArgs) options; })
+        optionsDocBook;
+      optionsMarkdown = pkgs.runCommand "options-markdown"
+        {
+          inherit (config.packages) optionsDocBook;
+          nativeBuildInputs = [ pkgs.pandoc ];
+        } ''
+        mkdir $out
+        pandoc \
+          --from docbook \
+          --to markdown \
+          --output $out/options.md \
+          $optionsDocBook
+      '';
+    };
+  };
+  flake = {
+    options.herculesCI = lib.mkOption { type = lib.types.raw; };
+    config.herculesCI = {
+      onPush.default.outputs = {
+        inherit (config.flake) packages checks;
+      };
+    };
+
+    # for repl exploration / debug
+    config.config = config;
+    options.mySystem = lib.mkOption { default = config.allSystems.${builtins.currentSystem}; };
+  };
+}

dev/flake.lock

@@ -0,0 +1,65 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "locked": {
+        "lastModified": 1619345332,
+        "narHash": "sha256-qHnQkEp1uklKTpx3MvKtY6xzgcqXDsz5nLilbbuL+3A=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "2ebf2558e5bf978c7fb8ea927dfaed8fefab2e28",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1652734403,
+        "narHash": "sha256-pIp7mRuYQd4JY2Ih4QaDjKVFgu7f1yHRRAvpb/rU9Mg=",
+        "owner": "hercules-ci",
+        "repo": "nixpkgs",
+        "rev": "0b02135d3bdf49f9154f60e7a4c9d54d5e0ee70d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "ref": "functionTo-properly",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "pre-commit-hooks-nix": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1638351750,
+        "narHash": "sha256-90OHC+11DIHD1QyMIPUuM3n6zjH5Mhc8RBZa0h8969A=",
+        "owner": "hercules-ci",
+        "repo": "pre-commit-hooks.nix",
+        "rev": "3bb289628867ac40fc9e7c514f8266b1ce8c0910",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "ref": "flakeModule",
+        "repo": "pre-commit-hooks.nix",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs",
+        "pre-commit-hooks-nix": "pre-commit-hooks-nix"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

dev/flake.nix

@@ -0,0 +1,18 @@
+{
+  description = "Dependencies for development purposes";
+
+  inputs = {
+    # Flakes don't give us a good way to depend on .., so we don't.
+    # This has drastic consequences of course.
+    nixpkgs.url = "github:hercules-ci/nixpkgs/functionTo-properly";
+
+    pre-commit-hooks-nix.url = "github:hercules-ci/pre-commit-hooks.nix/flakeModule";
+    pre-commit-hooks-nix.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = { self, ... }:
+    {
+      # Without good or dev outputs, we only use flakes for inputs here.
+      # The dev tooling is in ./flake-module.nix
+    };
+}

dev/repl.nix

@@ -0,0 +1,3 @@
+# convenience for loading into nix repl
+let self = builtins.getFlake (toString ./.);
+in self // { inherit self; }

lib.nix

@@ -3,6 +3,7 @@ let
   inherit (lib)
     mkOption
     types
+    functionTo
     ;
 
   flake-modules-core-lib = {
@@ -13,7 +14,7 @@ let
       module:
 
       lib.evalModules {
-        specialArgs = { inherit self flake-modules-core-lib; } // specialArgs;
+        specialArgs = { inherit self flake-modules-core-lib; inherit (self) inputs; } // specialArgs;
         modules = [ ./all-modules.nix module ];
       };
 
@@ -23,9 +24,23 @@ let
       options:
       mkOption {
         type = types.submoduleWith {
-          modules = [ { inherit options; } ];
+          modules = [{ inherit options; }];
         };
       };
+
+    mkPerSystemType =
+      module:
+      types.functionTo (types.submoduleWith {
+        modules = [ module ];
+        shorthandOnlyDefinesConfig = false;
+      });
+
+    mkPerSystemOption =
+      module:
+      mkOption {
+        type = flake-modules-core-lib.mkPerSystemType module;
+      };
+
   };
 
 in

modules/apps.nix

@@ -9,6 +9,7 @@ let
     ;
   inherit (flake-modules-core-lib)
     mkSubmoduleOptions
+    mkPerSystemOption
     ;
 
   programType = lib.types.coercedTo lib.types.package getExe lib.types.str;
@@ -18,13 +19,13 @@ let
 
   getBin = x:
     if !x?outputSpecified || !x.outputSpecified
-      then x.bin or x.out or x
-      else x;
+    then x.bin or x.out or x
+    else x;
 
   appType = lib.types.submodule {
     options = {
       type = mkOption {
-        type = lib.types.enum ["app"];
+        type = lib.types.enum [ "app" ];
         default = "app";
         description = ''
           A type tag for <literal>apps</literal> consumers.
@@ -48,13 +49,32 @@ in
         description = ''
           Programs runnable with nix run <literal>.#&lt;name></literal>.
         '';
-        example = lib.literalExample ''
+        example = lib.literalExpression or lib.literalExample ''
           {
             x86_64-linux.default.program = "''${config.packages.hello}/bin/hello";
           }
         '';
       };
     };
+
+    perSystem = mkPerSystemOption
+      ({ config, system, ... }: {
+        options = {
+          apps = mkOption {
+            type = types.lazyAttrsOf appType;
+            default = { };
+            description = ''
+              Programs runnable with nix run <literal>.#&lt;name></literal>.
+            '';
+            example = lib.literalExpression or lib.literalExample ''
+              {
+                default.program = "''${config.packages.hello}/bin/hello";
+              }
+            '';
+          };
+        };
+      });
+
   };
   config = {
     flake.apps =
@@ -70,22 +90,5 @@ in
         apps = flake.apps.${system};
       };
 
-    perSystem = system: { config, ... }: {
-      _file = ./apps.nix;
-      options = {
-        apps = mkOption {
-          type = types.lazyAttrsOf appType;
-          default = { };
-          description = ''
-            Programs runnable with nix run <literal>.#&lt;name></literal>.
-          '';
-          example = lib.literalExample ''
-            {
-              default.program = "''${config.packages.hello}/bin/hello";
-            }
-          '';
-        };
-      };
-    };
   };
 }

modules/checks.nix

@@ -9,6 +9,7 @@ let
     ;
   inherit (flake-modules-core-lib)
     mkSubmoduleOptions
+    mkPerSystemOption
     ;
 in
 {
@@ -22,6 +23,20 @@ in
         '';
       };
     };
+
+    perSystem = mkPerSystemOption ({ config, system, ... }: {
+      _file = ./checks.nix;
+      options = {
+        checks = mkOption {
+          type = types.lazyAttrsOf types.package;
+          default = { };
+          description = ''
+            Derivations to be built by nix flake check.
+          '';
+        };
+      };
+    });
+
   };
   config = {
     flake.checks =
@@ -37,17 +52,5 @@ in
         checks = flake.checks.${system};
       };
 
-    perSystem = system: { config, ... }: {
-      _file = ./checks.nix;
-      options = {
-        checks = mkOption {
-          type = types.lazyAttrsOf types.package;
-          default = { };
-          description = ''
-            Derivations to be built by nix flake check.
-          '';
-        };
-      };
-    };
   };
 }

modules/devShells.nix

@@ -9,6 +9,7 @@ let
     ;
   inherit (flake-modules-core-lib)
     mkSubmoduleOptions
+    mkPerSystemOption
     ;
 in
 {
@@ -19,10 +20,24 @@ in
         default = { };
         description = ''
           Per system an attribute set of packages used as shells.
-          nix develop .#<name> will run devShells.<system>.<name>.
+          <literal>nix develop .#&lt;name></literal> will run <literal>devShells.&lt;system>.&lt;name></literal>.
         '';
       };
     };
+
+    perSystem = mkPerSystemOption
+      ({ config, system, ... }: {
+        options = {
+          devShells = mkOption {
+            type = types.lazyAttrsOf types.package;
+            default = { };
+            description = ''
+              An attribute set of packages to be built by <literal>nix develop .#&lt;name></literal>.
+              <literal>nix build .#&lt;name></literal> will run <literal>devShells.&lt;name></literal>.
+            '';
+          };
+        };
+      });
   };
   config = {
     flake.devShells =
@@ -37,19 +52,5 @@ in
       optionalAttrs (flake?devShells.${system}) {
         devShells = flake.devShells.${system};
       };
-
-    perSystem = system: { config, ... }: {
-      _file = ./devShells.nix;
-      options = {
-        devShells = mkOption {
-          type = types.lazyAttrsOf types.package;
-          default = { };
-          description = ''
-            An attribute set of packages to be built by nix develop .#<name>.
-            nix build .#<name> will run devShells.<name>.
-          '';
-        };
-      };
-    };
   };
 }

modules/legacyPackages.nix

@@ -9,6 +9,7 @@ let
     ;
   inherit (flake-modules-core-lib)
     mkSubmoduleOptions
+    mkPerSystemOption
     ;
 in
 {
@@ -18,11 +19,24 @@ in
         type = types.lazyAttrsOf (types.lazyAttrsOf types.anything);
         default = { };
         description = ''
-          Per system, an attribute set of anything. This is also used by nix build .#<attrpath>.
+          Per system, an attribute set of anything. This is also used by <literal>nix build .#&lt;attrpath></literal>.
         '';
       };
     };
+
+    perSystem = mkPerSystemOption ({ config, ... }: {
+      options = {
+        legacyPackages = mkOption {
+          type = types.lazyAttrsOf types.anything;
+          default = { };
+          description = ''
+            An attribute set of anything. This is also used by <literal>nix build .#&lt;attrpath></literal>.
+          '';
+        };
+      };
+    });
   };
+
   config = {
     flake.legacyPackages =
       mapAttrs
@@ -37,17 +51,5 @@ in
         legacyPackages = flake.legacyPackages.${system};
       };
 
-    perSystem = system: { config, ... }: {
-      _file = ./legacyPackages.nix;
-      options = {
-        legacyPackages = mkOption {
-          type = types.lazyAttrsOf types.anything;
-          default = { };
-          description = ''
-            An attribute set of anything. This is also used by nix build .#<attrpath>.
-          '';
-        };
-      };
-    };
   };
 }

modules/packages.nix

@@ -9,6 +9,7 @@ let
     ;
   inherit (flake-modules-core-lib)
     mkSubmoduleOptions
+    mkPerSystemOption
     ;
 in
 {
@@ -19,10 +20,24 @@ in
         default = { };
         description = ''
           Per system an attribute set of packages.
-          nix build .#<name> will build packages.<system>.<name>.
+          <literal>nix build .#&lt;name></literal> will build <literal>packages.&lt;system>.&lt;name></literal>.
         '';
       };
     };
+
+    perSystem = mkPerSystemOption ({ config, ... }: {
+      _file = ./packages.nix;
+      options = {
+        packages = mkOption {
+          type = types.lazyAttrsOf types.package;
+          default = { };
+          description = ''
+            An attribute set of packages to be built by <literal>nix build .#&lt;name></literal>.
+            <literal>nix build .#&lt;name></literal> will build <literal>packages.&lt;name></literal>.
+          '';
+        };
+      };
+    });
   };
   config = {
     flake.packages =
@@ -38,18 +53,5 @@ in
         packages = flake.packages.${system};
       };
 
-    perSystem = system: { config, ... }: {
-      _file = ./packages.nix;
-      options = {
-        packages = mkOption {
-          type = types.lazyAttrsOf types.package;
-          default = { };
-          description = ''
-            An attribute set of packages to be built by nix build .#<name>.
-            nix build .#<name> will build packages.<name>.
-          '';
-        };
-      };
-    };
   };
 }

modules/perSystem.nix

@@ -1,4 +1,4 @@
-{ config, lib, self, ... }:
+{ config, lib, flake-modules-core-lib, self, ... }:
 let
   inherit (lib)
     genAttrs
@@ -6,6 +6,9 @@ let
     mkOption
     types
     ;
+  inherit (flake-modules-core-lib)
+    mkPerSystemType
+    ;
 
   rootConfig = config;
 
@@ -18,23 +21,18 @@ in
     };
 
     perInput = mkOption {
-      description = "Function from system to function from flake to system-specific attributes.";
+      description = "Function from system to function from flake to <literal>system</literal>-specific attributes.";
       type = types.functionTo (types.functionTo (types.lazyAttrsOf types.unspecified));
     };
 
     perSystem = mkOption {
-      description = "A function from system to flake-like attributes omitting the <system> attribute.";
-      type = types.functionTo (types.submoduleWith {
-        modules = [
-          ({ config, system, ... }: {
-            _file = ./perSystem.nix;
-            config = {
-              _module.args.inputs' = mapAttrs (k: rootConfig.perInput system) self.inputs;
-              _module.args.self' = rootConfig.perInput system self;
-            };
-          })
-        ];
-        shorthandOnlyDefinesConfig = false;
+      description = "A function from system to flake-like attributes omitting the <literal>&lt;system></literal> attribute.";
+      type = mkPerSystemType ({ config, system, ... }: {
+        _file = ./perSystem.nix;
+        config = {
+          _module.args.inputs' = mapAttrs (k: rootConfig.perInput system) self.inputs;
+          _module.args.self' = rootConfig.perInput system self;
+        };
       });
     };
 

shell.nix

@@ -0,0 +1,2 @@
+# non-idiomatic, see tools/README.md
+(import ./dev).devShells.${builtins.currentSystem}.default

template/multi-module/hello/flake-module.nix

@@ -1,4 +1,3 @@
-
 # Definitions can be imported from a separate file like this one
 
 { self, ... }: {
@@ -15,4 +14,4 @@
       ];
     };
   };
-}
+}