From ad46ca71df3d736141cf4cc2f39deac7b651bb22 Mon Sep 17 00:00:00 2001
From: Emery Hemingway <ehmry@posteo.net>
Date: Thu, 11 Jun 2020 10:26:10 +0530
Subject: [PATCH] Update README

---
 README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 109 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4207cbd..cd8d1b8 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 ```
-`      ______                     __           __
-      / ____/__  ____  ____  ____/ /__  ____  / / ____ ______
+``     ______                     __           __
+`     / ____/__  ____  ____  ____/ /__  ____  / / ____ ______
      / / __/ _ \/ __ \/ __ \/ __  / _ \/ __ \/ / / __ `/ ___/
     / /_/ /  __/ / / / /_/ / /_/ /  __/ /_/ / , \ /_/ (__  )
-    \____/\___/_/ /_/\____/\__,_/\___/ .___/_/ \_\_, /____/
-                                    /_/        /____/
+`   \____/\___/_/ /_/\____/\__,_/\___/ .___/_/ \_\_, /____/
+``                                  /_/        /____/
 ```
 
 [Genodepkgs](https://git.sr.ht/~ehmry/genodepkgs) is nexus of
@@ -25,7 +25,105 @@
 
  - Existing Nixpkgs packages are patched at [overlay](./overlay/default.nix)
 
- - Tests are at [tests](./tests/default.nix) (messy)
+ - Tests are at [tests](./tests/default.nix)
+
+ - NixOS module at [nixos-modules](./nixos-modules)
+
+# Installation
+
+This repository contains an experimental NixOS module that can be used to build
+and boot Genode using a shared Nix store. Hardware support is limited, and the
+system does not support any dynamic reconfiguration.
+
+NixOS must be installed on the target first, with many caveats. First of which,
+the block driver is hard-coded to use the media on the first AHCI port, port
+selection or NVMe simply hasn't been implemented within the Nix module.
+
+These instructions are non-normative have not be tested exactly as follows. This
+probably wont work for you.
+
+### Step 1: Install NixOS
+
+Format the first AHCI drive with a GUID Partition Table. */nix/store must be
+placed on a partition with the partition type
+`24b69406-18a1-428d-908e-d21a1437122c` and formatted with an Ext2 file-system.*
+Install NixOS, using Grub to boot. Use the `nixos-unstable` channel. See
+https://nixos.org/nixos/manual/index.html#ch-installation.
+
+### Step 2: Build Genode
+
+As mentioned before, the NixOS installation must be built from the
+`nixos-unstable` channel. This is to ensure that the `nixos-rebuild` utility is
+built with suport for taking configuration from Nix flakes.
+
+Create a file a `/etc/nixos/flake.nix` (or study the `nixos-rebuild` manual)
+with something similar to the following content:
+
+```nix
+{
+  description = "Example configuration flake";
+
+  inputs = {
+    genodepkgs.url = "git+https://git.sr.ht/~ehmry/genodepkgs";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = { self, genodepkgs, nixpkgs }: {
+
+    nixosConfigurations.${your-hostname-here} = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+
+        ./configuration.nix
+
+        genodepkgs.nixosModules.genodeHost
+
+        {
+          genode.fbDriver = "intel"; # or "vesa"
+          genode.guests = {
+            # Add two NixOS guest VMs to the Genode side:
+
+            nixos = {
+              config = { config, lib, pkgs, ... }: {
+                users.users.root.password = "nixos";
+                services.openssh.permitRootLogin = lib.mkDefault "yes";
+                services.mingetty.autologinUser = lib.mkDefault "root";
+              };
+            };
+
+            tor-browser = {
+              memorySize = 1024;
+              config = { config, lib, pkgs, ... }: {
+                services.cage = {
+                  enable = true;
+                  program = "${pkgs.tor-browser-bundle-bin}/bin/tor-browser";
+                };
+                users.users.demo.isNormalUser = true;
+              };
+            };
+
+          };
+
+        }
+      ];
+    };
+  };
+
+}
+
+```
+
+Do a `nixos-rebuild boot`. *Grub must be in use, UEFI booting is optional.*
+
+## Reboot
+
+Reboot and select the Genode entry from the Grub menu. Hopefully the display
+will come up quickly, and the VMs will boot. *The VMs will take a long time to
+come up initially,* this is because the VDI disk images are copied from
+/nix/store to a mutable area of the file-system.
+
+Thats all for now, patches are welcome.
+
 
 # Contributing
 
@@ -37,6 +135,12 @@ The worksites at the moment are:
 
  - Documentation
 
+ - Packaging multi-component scenarios
+
+ - Graphical launcher
+
+ - Port Boehm-Demers-Weiser GC to Genode
+
  - ARM, i686
 
  - Patching standard Nixpkgs packages by overlay. Explore Workflow and tooling