stuff

lib/README.md

@@ -0,0 +1,130 @@
+# mjallen-lib Utility Functions
+
+This directory contains utility functions that can be used to enhance your Nix configuration. These functions are inspired by the khanelinix repository and provide a more explicit and modular approach to building Nix configurations.
+
+## Directory Structure
+
+- `default.nix`: Main entry point that imports and exposes all utility functions
+- `module/`: Utilities for module creation and option handling
+- `file/`: Utilities for file handling and module discovery
+- `system/`: Utilities for system configuration building
+
+## How to Use
+
+### 1. Import the Library
+
+The library is already imported in your flake.nix file through the outputs-builder:
+
+```nix
+outputs-builder = channels: {
+  formatter = inputs.treefmt-nix.lib.mkWrapper channels.nixpkgs ./treefmt.nix;
+  
+  # Add mjallen-lib to the flake outputs
+  overlays = {
+    mjallen-lib = final: prev: {
+      mjallen-lib = (import ./lib { inherit inputs; }).mjallen-lib;
+    };
+  };
+};
+```
+
+This makes the mjallen-lib available to all your modules through the extended lib.
+
+### 2. Use the Module Utilities
+
+The module utilities provide functions for creating modules with consistent options:
+
+```nix
+{ lib, ... }:
+let
+  inherit (lib.mjallen.module) mkModule mkOpt mkBoolOpt;
+in
+mkModule {
+  name = "mymodule";
+  description = "My awesome module";
+  options = {
+    setting1 = mkOpt lib.types.str "default" "Description of setting1";
+    setting2 = mkBoolOpt false "Description of setting2";
+  };
+  config = {
+    # Module implementation
+  };
+}
+```
+
+### 3. Use the File Utilities
+
+The file utilities provide functions for file handling and module discovery:
+
+```nix
+{ lib, ... }:
+let
+  inherit (lib.mjallen.file) safeImport importModulesRecursive;
+in
+{
+  # Import a file with error handling
+  myConfig = safeImport ./my-config.nix {};
+  
+  # Import all modules recursively
+  imports = importModulesRecursive ./modules;
+}
+```
+
+### 4. Use the System Utilities
+
+The system utilities provide functions for building system configurations:
+
+```nix
+{ lib, ... }:
+let
+  inherit (lib.mjallen.system.common) mkHomeManagerConfig;
+in
+{
+  # Build home-manager configurations
+  homeManagerConfig = mkHomeManagerConfig {
+    extendedLib = lib;
+    inputs = inputs;
+    system = "x86_64-linux";
+    matchingHomes = { ... };
+  };
+}
+```
+
+## Available Functions
+
+### Module Utilities
+
+- `mkModule`: Create a module with common options
+- `mkOpt`: Create an option with a type, default value, and description
+- `mkOpt'`: Create an option with a type and default value (no description)
+- `mkBoolOpt`: Create a boolean option with a default value and description
+- `mkBoolOpt'`: Create a boolean option with a default value (no description)
+- `enabled`: Standard enable pattern
+- `disabled`: Standard disable pattern
+- `capitalize`: Capitalize a string
+- `boolToNum`: Convert a boolean to a number
+- `default-attrs`: Apply mkDefault to all attributes
+- `force-attrs`: Apply mkForce to all attributes
+- `nested-default-attrs`: Apply default-attrs to nested attributes
+- `nested-force-attrs`: Apply force-attrs to nested attributes
+
+### File Utilities
+
+- `readFile`: Read a file and return its contents
+- `pathExists`: Check if a file exists
+- `safeImport`: Import a nix file with error handling
+- `scanDir`: Scan a directory and return directory names
+- `getFile`: Get a file path relative to the flake root
+- `importModulesRecursive`: Recursively discover and import all Nix modules in a directory tree
+- `scanSystems`: Recursively scan systems directory structure
+- `filterNixOSSystems`: Filter systems for NixOS (Linux)
+- `filterDarwinSystems`: Filter systems for Darwin (macOS)
+- `scanHomes`: Scan homes directory structure for home configurations
+
+### System Utilities
+
+- `mkExtendedLib`: Extend the nixpkgs lib with mjallen-lib
+- `mkNixpkgsConfig`: Create a nixpkgs configuration
+- `mkHomeConfigs`: Create home configurations for a system and hostname
+- `mkHomeManagerConfig`: Create a home-manager configuration
+- `mkSpecialArgs`: Create special arguments for a system configuration