readme: extract example to own runnable file

3 files changed, 97 insertions, 92 deletions

diff --git a/example/flake.nix b/example/flake.nix
new file mode 100644
index 0000000..8557265
--- /dev/null
+++ b/example/flake.nix
@@ -0,0 +1,88 @@
+{
+  description = "Example of a Flake using flaky-utils.";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-22.05";
+    flake-utils.url = "github:numtide/flake-utils";
+    flaky-utils.url = "git+https://cgit.pacien.net/libs/flaky-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils, flaky-utils }:
+  flake-utils.lib.eachDefaultSystem (system: let
+    pkgs = import nixpkgs { inherit system; };
+  in pkgs.lib.fold pkgs.lib.recursiveUpdate { } [
+
+    {
+      # Convenience development shell providing some tools.
+      #
+      # The binaries made available and the environment variable set are
+      # printed when entering the shell.
+      #
+      # The user's default shell is used instead of Bash (sacrifying a bit of
+      # reproducibility for convenience).
+      #
+      devShell = flaky-utils.lib.mkDevShell {
+        inherit pkgs;
+
+        tools = with pkgs; [
+          postgresql_14
+          pgcli
+        ];
+
+        envVars = rec {
+          PGDATA = "$PWD/development_database/pgdata";
+          PGHOST = "$PWD/development_database";
+          PGPORT = "5432";
+          PGDATABASE = "app";
+          DATABASE_URL = "postgresql:///${PGDATABASE}?host=${PGHOST}";
+        };
+
+        shell = null;
+      };
+    }
+
+    # Convenience isolated environment using a QEMU virtual machine.
+    #
+    # This defines a triplet of nixosConfiguration, package and app with the
+    # given name, so that the virtual machine can be launched using
+    # a command like `nix run .#sandbox`.
+    #
+    # By default, the VM is launched in the current console without a graphical
+    # interface, dropping to a shell for the default dummy user within.
+    #
+    # The current working directory from which the Flake is run is mounted and
+    # made available within the virtual machine in /mnt. The root filesystem
+    # is ephemeral (written to a temporary file in /tmp).
+    #
+    # The virtual machine's network is isolated by default: it cannot access
+    # the Internet nor the host's local network. Ports may nevertheless be
+    # forwarded explicitly from host to guest and vice-versa.
+    #
+    (flaky-utils.lib.mkSandboxSystem {
+      inherit nixpkgs system;
+
+      name = "sandbox";
+      user = "dummy";
+
+      config = {
+        virtualisation.forwardPorts = [
+          { from = "host"; host.port = 5432; guest.port = 5432; }  # postgres
+        ];
+
+        services.postgresql = {
+          enable = true;
+          enableTCPIP = true;
+
+          authentication = ''
+            host all all 0.0.0.0/0 trust
+          '';
+
+          initialScript = pkgs.writeText "init.sql" ''
+            create role dummy login superuser;
+          '';
+        };
+      };
+    })
+
+  ]);
+}
diff --git a/example/nix.sh b/example/nix.sh
new file mode 100755
index 0000000..748c80c
--- /dev/null
+++ b/example/nix.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+
+nix \
+  "$1" \
+  --no-update-lock-file \
+  --no-write-lock-file \
+  --override-input flaky-utils ../ \
+  "${@:2}"
diff --git a/readme.md b/readme.md
index 853c3cc..649d53c 100644
--- a/readme.md
+++ b/readme.md
@@ -8,98 +8,7 @@ No promise on API stability.
 
 ## Usage
 
-Functions documentation provided as comments below.
-
-```nix
-{
-  description = "Example of a Flake using flaky-utils.";
-
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-22.05";
-    flake-utils.url = "github:numtide/flake-utils";
-    flaky-utils.url = "git+https://cgit.pacien.net/libs/flaky-utils";
-  };
-
-  outputs = { self, nixpkgs, flake-utils, flaky-utils }:
-  flake-utils.lib.eachDefaultSystem (system: let
-    pkgs = import nixpkgs { inherit system; };
-  in pkgs.lib.fold pkgs.lib.recursiveUpdate { } [
-
-    {
-      # Convenience development shell providing some tools.
-      #
-      # The binaries made available and the environment variable set are
-      # printed when entering the shell.
-      #
-      # The user's default shell is used instead of Bash (sacrifying a bit of
-      # reproducibility for convenience).
-      #
-      devShell = flaky-utils.lib.mkDevShell {
-        inherit pkgs;
-
-        tools = with pkgs; [
-          postgresql_14
-          pgcli
-        ];
-
-        envVars = rec {
-          PGDATA = "$PWD/development_database/pgdata";
-          PGHOST = "$PWD/development_database";
-          PGPORT = "5432";
-          PGDATABASE = "app";
-          DATABASE_URL = "postgresql:///${PGDATABASE}?host=${PGHOST}";
-        };
-
-        shell = null;
-      };
-    }
-
-    # Convenience isolated environment using a QEMU virtual machine.
-    #
-    # This defines a triplet of nixosConfiguration, package and app with the
-    # given name, so that the virtual machine can be launched using
-    # a command like `nix run .#sandbox`.
-    #
-    # By default, the VM is launched in the current console without a graphical
-    # interface, dropping to a shell for the default dummy user within.
-    #
-    # The current working directory from which the Flake is run is mounted and
-    # made available within the virtual machine in /mnt. The root filesystem
-    # is ephemeral (written to a temporary file in /tmp).
-    #
-    # The virtual machine's network is isolated by default: it cannot access
-    # the Internet nor the host's local network. Ports may nevertheless be
-    # forwarded explicitly from host to guest and vice-versa.
-    #
-    (flaky-utils.lib.mkSandboxSystem {
-      inherit nixpkgs system;
-
-      name = "sandbox";
-      user = "dummy";
-
-      config = {
-        virtualisation.forwardPorts = [
-          { from = "host"; host.port = 5432; guest.port = 5432; }  # postgres
-        ];
-
-        services.postgresql = {
-          enable = true;
-          enableTCPIP = true;
-
-          authentication = ''
-            host all all 0.0.0.0/0 trust
-          '';
-
-          initialScript = pkgs.writeText "init.sql" ''
-            create role dummy login superuser;
-          '';
-        };
-      };
-    })
-
-  ]);
-}
-```
+See "./example/flake.nix" for a documented example.
 
 
 ## Contributing