From 364b5310d6a680ed898874203495cd6ef212b9e7 Mon Sep 17 00:00:00 2001
From: zimbatm <zimbatm@zimbatm.com>
Date: Wed, 22 Apr 2020 17:33:24 +0200
Subject: [PATCH] better docs

---
 .gitignore        |  6 +++++
 README.md         | 61 ++++++++++++++++++++++++++++++++---------------
 example/flake.nix |  3 +--
 3 files changed, 49 insertions(+), 21 deletions(-)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c61512f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,6 @@
+# Nix
+result
+result-*
+
+# Don't keep the example lockfile around
+/example/flake.lock
diff --git a/README.md b/README.md
index 9b46702..d3f27da 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # flake-utils
 
-**STATUS: WIP**
+**STATUS: alpha**
 
 Pure Nix flake utility functions.
 
@@ -10,31 +10,54 @@ flakes.
 
 ## Usage
 
-`flake.nix`
+### `defaultSystems -> [<system>]`
+
+A list of all the systems supported by the nixpkgs project.
+
+### `eachSystem -> [<system>] -> (<system> -> attrs)`
+
+A common case is to build the same structure for each system. Instead of
+building the hierarchy manually or per prefix, iterate over each systems and
+then re-build the hierarchy.
+
+Eg:
+
+```nix
+eachSystem ["x86-64-linux"] (system: { hello = 42; })
+# => { hello.x86-64-linux.hello = 42; }
+```
+
+### `eachDefaultSystem -> (<system> -> attrs)`
+
+`eachSystem` pre-populated with `defaultSystems`.
+
+### `mkApp { drv, name ? drv.pname or drv.name, execPath ? drv.passthru.execPath or "/bin/${name}"`
+
+A small utility that builds the structure expected by the special `apps` and `defaultApp` prefixes.
+
+## Example
+
+Here is how it looks like in practice:
+
+[$ example/flake.nix](example/flake.nix) as nix
 ```nix
 {
+  description = "Flake utils demo";
   edition = 201909;
-  description = "My flake";
-  inputs = {
-    utils = { type = "github"; owner = "numtide"; repo = "flake-utils"; };
+
+  inputs.utils = {
+    uri = "github:numtide/flake-utils";
   };
+
   outputs = { self, nixpkgs, utils }:
-    utils.eachDefaultSystem (system:
+    utils.lib.eachDefaultSystem (system:
       let pkgs = nixpkgs.legacyPackages.${system}; in
       rec {
-        packages = {
-          my-app = pkgs.callPackage ./my-app.nix {};
-        };
-
-        defaultPackage = package.my-app;
-
-        apps = {
-          my-app = flake.mkApp packages.my-app;
-        };
-
-        defaultApp = apps.my-app;
-      };
+        packages.hello = pkgs.hello;
+        defaultPackage = packages.hello;
+        apps.hello = utils.lib.mkApp { drv = packages.hello; };
+        defaultApp = apps.hello;
+      }
     );
 }
 ```
-
diff --git a/example/flake.nix b/example/flake.nix
index d877b0e..0fb49e7 100644
--- a/example/flake.nix
+++ b/example/flake.nix
@@ -3,8 +3,7 @@
   edition = 201909;
 
   inputs.utils = {
-    type = "git";
-    uri = "file:///home/zimbatm/go/src/github.com/zimbatm/flake-utils";
+    uri = "github:numtide/flake-utils";
   };
 
   outputs = { self, nixpkgs, utils }: