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:

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:

{ 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:

{ 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:

{ 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