From bca532ab42f23aed8a9379f7e56737a952b52223 Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Mon, 1 Mar 2021 14:00:18 -0500
Subject: [PATCH 1/2] lib: can depend on pkgs (a la nixpkgs#pkgs/pkgs-lib)

---
 flake.nix       | 2 +-
 lib/default.nix | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/flake.nix b/flake.nix
index 4142656e..caa700b4 100644
--- a/flake.nix
+++ b/flake.nix
@@ -65,7 +65,7 @@
 
           overlay = import ./pkgs;
 
-          lib = import ./lib { inherit nixos; };
+          lib = import ./lib { inherit nixos pkgs; };
 
           templates.flk.path = ./.;
 
diff --git a/lib/default.nix b/lib/default.nix
index c60880c2..74e74cf1 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -1,4 +1,4 @@
-{ nixos, ... }:
+{ nixos, pkgs, ... }:
 let
   inherit (builtins) attrNames attrValues isAttrs readDir listToAttrs mapAttrs
     pathExists filter;

From e56c619aef7da69292a2ae9b9b3582edce4d898a Mon Sep 17 00:00:00 2001
From: David Arnold <dar@xoe.solutions>
Date: Mon, 1 Mar 2021 14:37:43 -0500
Subject: [PATCH 2/2] lib: add usage docs

---
 SUMMARY.md    |  1 +
 lib/README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 lib/README.md

diff --git a/SUMMARY.md b/SUMMARY.md
index c862768e..331ff7ce 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -8,6 +8,7 @@
   - [Cachix](./cachix/README.md)
   - [Extern](./extern/README.md)
   - [Hosts](./hosts/README.md)
+  - [Lib](./lib/README.md)
   - [Modules](./modules/README.md)
   - [Overlays](./overlays/README.md)
   - [Overrides](./overrides/README.md)
diff --git a/lib/README.md b/lib/README.md
new file mode 100644
index 00000000..ed19b1a3
--- /dev/null
+++ b/lib/README.md
@@ -0,0 +1,88 @@
+# Lib
+The lib directory mirrors the upstream concepts of [`nixpkgs:./lib`][nixpkgs-lib], 
+[`nixpkgs:./nixos/lib`][nixpkgs-nixos-lib] and [`nixpkgs:./pkgs/pkgs-lib`][nixpkgs-pkgs-lib],
+but also occasionally [`nixpkgs:./pkgs/build-support`][nixpkgs-pkgs-build-support].
+
+It comes with functions necesary to declutter `devos` itself, but you are
+welcome to extend it to your needs.
+
+For example:
+
+- you want to add a library function that depends on some packages
+and use it throughout your devos environment: place it into `./lib`
+as if you would place it into [`nixpkgs:./pkgs/pkgs-lib`][nixpkgs-pkgs-lib].
+
+- you want to add library functions that don't depend on `pkgs`: place
+them into `./lib` as if you would place them into [`nixpkgs:./lib`][nixpkgs-lib].
+
+- need to try out a newish custom build support: place it here before
+upstreaming into [`nixpkgs:./pkgs/build-support`][nixpkgs-pkgs-build-support].
+
+- you want to reutilize certain module configuration functions or helpers:
+place them into `./lib` as if you would place them into [`nixpkgs:./nixos/lib`][nixpkgs-nixos-lib].
+
+Once your library grows, we recoomend you start organizing them into subfolders
+analogous `nixpkgs`:
+
+| `nixpkgs`              | `devos`            |
+| ---------------------- | ------------------ |
+| `./lib`                | `./lib`            |
+| `./pkgs/pkgs-lib`      | `./lib/pkgs-lib`   |
+| `./nixos/lib`          | `./lib/nixos-lib`  |
+| `./pkgs/build-support` | `./lib/pkgs-build` |
+
+
+## Example
+lib/nixos-lib/mkCustomI3BindSym/default.nix:
+```nix
+{ pkgs, writers, ... }:
+{ name, cmd, workspace, baseKey }:
+let
+  isWorkspaceEmpty = writers.writePython3 "is-workspace-empty" {
+    libraries = [ pkgs.python3Packages.i3ipc ];
+  } (builtins.readFile ./is-workspace-empty.py);
+
+  ws = builtins.toString workspace;
+in
+''
+
+  # ${name}
+  #bindsym ${baseKey}+${ws} workspace ${ws}; exec ${cmd}
+  bindsym ${baseKey}+${ws} workspace ${ws}; exec bash -c "${isWorkspaceEmpty} && ${cmd}"
+''
+```
+
+lib/nixos-lib/mkCustomI3BindSym/is-workspace-empty.py:
+```python
+# returns 0/1 if current workspace is empty/non-empty
+
+import i3ipc
+
+i3 = i3ipc.Connection()
+tree = i3.get_tree()
+
+
+def current_workspace():
+    return tree.find_focused().workspace()
+
+
+if current_workspace().leaves():
+    print("Error current workspace is not empty")
+    exit(1)
+exit(0)
+```
+
+lib/default.nix:
+```nix
+{ nixos, pkgs, ... }:
+# ...
+{
+  # ...
+  mkCustomI3BindSym = pkgs.callPackage ./nixos-lib/mkCustomI3BindSym { };
+}
+```
+
+[nixpkgs-lib]: https://github.com/NixOS/nixpkgs/tree/master/lib
+[nixpkgs-pkgs-lib]: https://github.com/NixOS/nixpkgs/tree/master/pkgs/pkgs-lib
+[nixpkgs-pkgs-build-support]: https://github.com/NixOS/nixpkgs/tree/master/pkgs/build-support
+[nixpkgs-nixos-lib]: https://github.com/NixOS/nixpkgs/tree/master/nixos/lib