From 7b2e0c17b7f62cc3e79317014fe3759ab3dc49a9 Mon Sep 17 00:00:00 2001
From: Daniel Langbein <daniel@systemli.org>
Date: Tue, 5 Sep 2023 17:54:40 +0200
Subject: [PATCH] update README

---
 README.md | 89 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 65 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 08dfae6..eaaa761 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 For each host (server, laptop, etc.), there is a subdirectory inside [hosts](hosts).
 
-## NixOS Installation
+## NixOS installation
 
 For beginners, NixOS can be installed with a graphical installer.
 
@@ -17,7 +17,7 @@ During installation, select manual partitioning:
 * One 512MB (or larger) Fat32 partition, mounted at `/boot`, "boot" flag enabled
 * Another partition (e.g. BTRFS) covering the rest of the drive, mounted at `/`, encryption enabled
 
-## Build and Switch
+## Build and switch
 
 * https://nixos.wiki/wiki/Nixos-rebuild
 
@@ -41,7 +41,7 @@ niv update
 
 Then run `nixos-rebuild switch`, see above.
 
-## Garbage Collection
+## Garbage collection
 
 * https://nixos.org/manual/nix/stable/package-management/garbage-collection.html
 * https://discourse.nixos.org/t/why-doesnt-nix-collect-garbage-remove-old-generations-from-efi-menu/17592/4
@@ -58,26 +58,6 @@ Remove old generations from EFI:
 sudo /run/current-system/bin/switch-to-configuration boot
 ```
 
-## Evaluate configuration.nix to JSON
-
-TODO: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-show-config.html
-
-* https://discourse.nixos.org/t/can-i-run-nix-instantiate-eval-strict-on-my-configuration-nix/7105/4
-
-This evaluates `configuration.nix` (single module):
-
-```shell
-NIXPKGS_ALLOW_UNFREE=1 nix-instantiate --strict --json --eval -E '
-import ./hosts/yodaTab/configuration.nix  {
-  config = {};
-  pkgs = import <nixpkgs> {};
-  lib = import <nixpkgs/lib>;
-}
-' > evaluated-config.json
-```
-
-Then open [evaluated-config.json](evaluated-config.json).
-
 ## Install Home Manager with niv
 
 niv:
@@ -141,7 +121,7 @@ Summary:
 * Regenerate hardware-configuration: `sudo nixos-generate-config --dir $(hostname)`
 * Add `swapDevices = [ { device = "/swap/swapfile"; } ];` to hardware configuration and run `nixos-rebuild switch` (see above).
 
-## Automount Encrypted Drive
+## Automount encrypted drive
 
 * Generate and add keyfile to LUKS device
 * luksOpen and mount drive, e.g. to `/mnt/data1`
@@ -245,6 +225,67 @@ Excerpt of the result:
 /nix/store/jqvxmx65mfinbsm6db9kmcqmphl44xhp-nano-7.2/share/nano/autoconf.nanorc
 ```
 
+### NixOS configuration debugging
+
+* https://nixos.wiki/wiki/Nix_command/repl
+
+Evaluating parts of the configuration.
+
+First, start `nix repl`:
+
+```shell
+nix repl --file '<nixpkgs/nixos>' -I nixos-config=hosts/$(hostname)/configuration.nix
+```
+
+Example: `config.home-manager`
+
+```shell
+config.home-manager.
+# Press `TAB`
+#=> config.home-manager.backupFileExtension  config.home-manager.useUserPackages
+#=> config.home-manager.extraSpecialArgs     config.home-manager.users
+#=> config.home-manager.sharedModules        config.home-manager.verbose
+#=> config.home-manager.useGlobalPkgs
+```
+
+Example: The `home` variable:
+
+```shell
+config.home-manager.users.yoda.home
+```
+
+Example: The value of one config option
+
+```shell
+# The following option is set to `"${config.xdg.dataHome}/.histfile";`
+# where `config` is the Home Manager configuration.
+
+config.home-manager.users.yoda.programs.zsh.history.path
+#=> "/home/yoda/.local/share/.histfile"
+```
+
+### Evaluate NixOS configuration to JSON
+
+See also section "NixOS Configuration Debugging"!
+
+TODO: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-show-config.html
+
+* https://discourse.nixos.org/t/can-i-run-nix-instantiate-eval-strict-on-my-configuration-nix/7105/4
+
+This evaluates `configuration.nix` (single module):
+
+```shell
+NIXPKGS_ALLOW_UNFREE=1 nix-instantiate --strict --json --eval -E '
+import ./hosts/yodaTab/configuration.nix  {
+  config = {};
+  pkgs = import <nixpkgs> {};
+  lib = import <nixpkgs/lib>;
+}
+' > evaluated-config.json
+```
+
+Then open [evaluated-config.json](evaluated-config.json).
+
 ### References
 
 Some references to websites that helped me create this repository: