From 4184cbcd037b79ed627aca20798810518cb328ac Mon Sep 17 00:00:00 2001
From: lassulus <lassulus@lassul.us>
Date: Sun, 23 Oct 2022 12:29:30 +0200
Subject: add module

---
 README.md | 194 ++++++++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 127 insertions(+), 67 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index eb06ac8..f448455 100644
--- a/README.md
+++ b/README.md
@@ -1,80 +1,140 @@
-disko
-=====
+# disko
 
-nix-powered automatic disk partitioning
+nix-powered automatic disk partitioning.  partition your disks declaratively NixOS style.
 
-Usage
-=====
+## Installing NixOS module
 
-Master Boot Record
-------------------
-This is how your iso configuation may look like
+You can use the NixOS module in one of the following ways:
+
+### Flakes
+
+If you use nix flakes support:
+
+``` nix
+{
+  inputs.disko.url = "github:nix-community/disko";
+  inputs.disko.inputs.nixpkgs.follows = "nixpkgs";
+
+  outputs = { self, nixpkgs, disko }: {
+    # change `yourhostname` to your actual hostname
+    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
+      # change to your system:
+      system = "x86_64-linux";
+      modules = [
+        ./configuration.nix
+        disko.nixosModules.disko
+      ];
+    };
+  };
+}
+```
+
+### [niv](https://github.com/nmattia/niv) (Current recommendation)
+  First add it to niv:
+
+```console
+$ niv add nix-community/disko
+```
+
+  Then add the following to your configuration.nix in the `imports` list:
 
-/etc/nixos/configuration.nix
 ```nix
-{ pkgs, modulesPath, ... }:
-let
-  disko = pkgs.callPackage (builtins.fetchGit {
-    url = "https://github.com/nix-community/disko";
-    ref = "master";
-  }) {};
-  cfg = {
-    disk = {
-      sda = {
-        device = "/dev/sda";
-        type = "device";
-        content = {
-          type = "table";
-          format = "msdos";
-          partitions = [
-            {
-              name = "root";
-              type = "partition";
-              part-type = "primary";
-              start = "1M";
-              end = "100%";
-              bootable = true;
-              content = {
-                type = "filesystem";
-                format = "ext4";
-                mountpoint = "/";
-              };
-            }
-          ];
-        };
+{
+  imports = [ "${(import ./nix/sources.nix).disko}/modules/disko.nix" ];
+}
+```
+
+### nix-channel
+
+  As root run:
+
+```console
+$ nix-channel --add https://github.com/nix-community/disko/archive/main.tar.gz disko
+$ nix-channel --update
+```
+
+  Then add the following to your configuration.nix in the `imports` list:
+
+```nix
+{
+  imports = [ <disko/modules/disko.nix> ];
+}
+```
+
+### fetchTarball
+
+  Add the following to your configuration.nix:
+
+``` nix
+{
+  imports = [ "${builtins.fetchTarball "https://github.com/nix-community/disko/archive/main.tar.gz"}/modules/disko.nix" ];
+}
+```
+
+  or with pinning:
+
+```nix
+{
+  imports = let
+    # replace this with an actual commit id or tag
+    commit = "f2783a8ef91624b375a3cf665c3af4ac60b7c278";
+  in [ 
+    "${builtins.fetchTarball {
+      url = "https://github.com/nix-community/disko/archive/${commit}.tar.gz";
+      # replace this with an actual hash
+      sha256 = "0000000000000000000000000000000000000000000000000000";
+    }}/module.nix"
+  ];
+}
+```
+
+## Using the NixOS module
+
+```nix
+{
+  # checkout the example folder for how to configure different diska layouts
+  disko.devices = {
+    disk.sda = {
+      device = "/dev/sda";
+      type = "disk";
+      content = {
+        type = "table";
+        format = "gpt";
+        partitions = [
+          {
+            type = "partition";
+            name = "ESP";
+            start = "1MiB";
+            end = "100MiB";
+            bootable = true;
+            content = {
+              type = "filesystem";
+              format = "vfat";
+              mountpoint = "/boot";
+            };
+          }
+          {
+            name = "root";
+            type = "partition";
+            start = "100MiB";
+            end = "100%";
+            part-type = "primary";
+            bootable = true;
+            content = {
+              type = "filesystem";
+              format = "ext4";
+              mountpoint = "/";
+            };
+          }
+        ];
       };
     };
   };
-in {
-  imports = [
-    (modulesPath + "/installer/cd-dvd/installation-cd-minimal.nix")
-  ];
-  environment.systemPackages = with pkgs;[
-    (pkgs.writeScriptBin "tsp-create" (disko.create cfg))
-    (pkgs.writeScriptBin "tsp-mount" (disko.mount cfg))
-  ];
-  ## Optional: Automatically creates a service which runs at startup to perform the partitioning
-  #systemd.services.install-to-hd = {
-  #  enable = true;
-  #  wantedBy = ["multi-user.target"];
-  #  after = ["getty@tty1.service" ];
-  #  serviceConfig = {
-  #    Type = "oneshot";
-  #    ExecStart = [ (disko.create cfg) (disk.mount cfg) ];
-  #    StandardInput = "null";
-  #    StandardOutput = "journal+console";
-  #    StandardError = "inherit";
-  #  };
-  #};
 }
 ```
 
-After `nixos-rebuild switch` this will add a `tsp-create` and a `tsp-mount`
-command:
+this will configure `fileSystems` and other required NixOS options to boot the specified configuration.
 
-- **tsp-create**: creates & formats the partitions according to `tsp-disk.json`
-- **tsp-mount**: mounts the partitions to `/mnt`
+If you are on an installer, you probably want to disable `enableConfig`.
 
-GUID Partition Table, LVM and dm-crypt
---------------------------------------
-See `examples/`
+disko will create the scripts `disko-create` and `disko-mount` which can be used to create/mount the configured disk layout.
-- 
cgit v1.2.3