From e56c619aef7da69292a2ae9b9b3582edce4d898a Mon Sep 17 00:00:00 2001 From: David Arnold Date: Mon, 1 Mar 2021 14:37:43 -0500 Subject: [PATCH] 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