Add template rewrite README sections

README.md

@@ -5,52 +5,51 @@ _Foundational flake attributes represented using the module system._
 
 `flake-modules-core` provides common options for an ecosystem of modules to extend.
 
-This allows anyone to bundle up tooling into reusable modules.
+# Why Modules?
 
-For users, this makes Flakes easier to wire up.
+Flakes are configuration. The module system lets you refactor configuration
+into modules that can be shared.
 
-_Non-goals_:
+It reduces the proliferation of custom Nix glue code, similar to what the
- - Replace general Nix expressions, which are needed for advanced and/or ad-hoc use cases.
+module system has done for NixOS configurations.
- - Accumulate everything into a single repository. As the name might suggest, it focuses only on options that have to do with well-known Nix Flakes attributes.
 
+Unlike NixOS, but following Flakes' spirit, `flake-modules-core` is not a
+monorepo with the implied goal of absorbing all of open source, but rather
+a single module that other repositories can build upon, while ensuring a
+baseline level of compatibility: which core attribute make up a flake and
+how these are represented as module options.
 
-# Example Flake
+# Getting Started
 
-```nix
+If your project does not have a flake yet:
-{
-  description = "A very basic flake";
 
-  inputs = {
+```console
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+nix flake init -t github:hercules-ci/flake-modules-core
+```
+
+Otherwise, add the input,
+
+```
     flake-modules-core.url = "github:hercules-ci/flake-modules-core";
     flake-modules-core.inputs.nixpkgs.follows = "nixpkgs";
-    devshell.url = "github:hercules-ci/devshell/flake-modules"; # credit to numtide
+```
-  };
 
-  outputs = { self, nixpkgs, flake-modules-core, devshell, ... }:
+then slide `evalFlakeModule` between your outputs function head and body,
+
+```
+  outputs = { self, flake-modules-core, ... }:
     (flake-modules-core.lib.evalFlakeModule
       { inherit self; }
       {
-        systems = [ "x86_64-linux" ];
-        imports = [
-          devshell.flakeModule
-        ];
         flake = {
-          nixosConfigurations.foo = lib.nixosSystem { /* ... */ };
+          # Put your original flake attributes here.
-        };
-        perSystem = system: { config, pkgs, self', inputs', ... }: {
-          _module.args.pkgs = inputs'.nixpkgs.legacyPackages;
-          devshell.settings.commands = [
-            {
-              help = "format nix code";
-              package = pkgs.nixpkgs-fmt;
         }
-          ];
+      }
-          packages.hello = pkgs.hello;
+    ).config.flake;
-          packages.hello2 = self'.packages.hello;
-          checks.hello = self'.packages.hello;
-        };
-      }).config.flake;
-
-}
 ```
+
+Now you can add the remaining module attributes like in the [the template](./template/flake.nix).
+
+# Example
+
+See [the template](./template/flake.nix).

flake.nix

@@ -7,6 +7,12 @@
 
   outputs = { self, nixpkgs, ... }: {
     lib = import ./lib.nix { inherit (nixpkgs) lib; };
+    defaultTemplate = {
+      path = ./template;
+      description = ''
+        A minimal flake using flake-modules-core.
+      '';
+    };
   };
 
 }

template/flake.nix

@@ -0,0 +1,37 @@
+{
+  description = /* ... */;
+
+  inputs = {
+    flake-modules-core.url = "github:hercules-ci/flake-modules-core";
+    flake-modules-core.inputs.nixpkgs.follows = "nixpkgs";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = { self, flake-modules-core, ... }:
+    (flake-modules-core.lib.evalFlakeModule
+      { inherit self; }
+      {
+        imports = [
+          # To import a flake module
+          # 1. Add foo to inputs
+          # 2. Add foo as a parameter to the outputs function
+          # 3. Add here: foo.flakeModule
+
+        ];
+        systems = [ "x86_64-linux" "aarch64-darwin" ];
+        perSystem = system: { config, self', inputs', ... }: {
+          # Per-system attributes can be defined here. The self' and inputs'
+          # module parameters provide easy access to attributes of the same
+          # system.
+
+          packages.hello = inputs'.nixpkgs.legacyPackages.hello;
+        };
+        flake = {
+          # The usual flake attributes can be defined here, including system-
+          # agnostic ones like nixosModule and system-enumerating ones, although
+          # those are more easily expressed in perSystem.
+
+        };
+      }
+    ).config.flake;
+}