feat: update documentation, lib functions, modules, and packages
Some checks failed
Update Nix Packages with nix-update / nix-update (push) Failing after 3h23m59s
Some checks failed
Update Nix Packages with nix-update / nix-update (push) Failing after 3h23m59s
This commit is contained in:
m3tm3re
@@ -20,29 +20,16 @@ Step-by-step guides for common tasks:
|
||||
|
||||
- [Getting Started](./guides/getting-started.md) - Initial setup and basic usage
|
||||
- [Adding Packages](./guides/adding-packages.md) - How to add new packages
|
||||
- [Adding Modules](./guides/adding-modules.md) - How to add new NixOS or Home Manager modules
|
||||
- [Port Management](./guides/port-management.md) - Managing service ports across hosts
|
||||
- [Using Modules](./guides/using-modules.md) - Using NixOS and Home Manager modules
|
||||
- [Development Workflow](./guides/development-workflow.md) - Development and testing workflow
|
||||
|
||||
### 📦 Packages
|
||||
|
||||
Documentation for all custom packages:
|
||||
|
||||
- [code2prompt](./packages/code2prompt.md) - Convert code to prompts
|
||||
- [hyprpaper-random](./packages/hyprpaper-random.md) - Random wallpaper setter for Hyprpaper
|
||||
- [kestractl](./packages/kestractl.md) - CLI for the Kestra workflow orchestration platform
|
||||
- [launch-webapp](./packages/launch-webapp.md) - Launch web applications
|
||||
- [mem0](./packages/mem0.md) - AI memory assistant with vector storage
|
||||
- [msty-studio](./packages/msty-studio.md) - Msty Studio application
|
||||
- [n8n](./packages/n8n.md) - Free and source-available fair-code licensed workflow automation tool
|
||||
- [notesmd-cli](./packages/notesmd-cli.md) - Obsidian CLI (Community) - Interact with Obsidian in the terminal
|
||||
- [pomodoro-timer](./packages/pomodoro-timer.md) - Pomodoro timer utility
|
||||
- [rofi-project-opener](./packages/rofi-project-opener.md) - Rofi-based project launcher with custom args
|
||||
- [sidecar](./packages/sidecar.md) - Companion tool for CLI agents with diffs, file trees, and task management
|
||||
- [stt-ptt](./packages/stt-ptt.md) - Push to Talk Speech to Text using Whisper
|
||||
- [td](./packages/td.md) - Minimalist CLI for tracking tasks across AI coding sessions
|
||||
- [tuxedo-backlight](./packages/tuxedo-backlight.md) - Backlight control for Tuxedo laptops
|
||||
- [zellij-ps](./packages/zellij-ps.md) - Project switcher for Zellij
|
||||
- [Packages Index](./packages/) - All packages with descriptions
|
||||
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
|
||||
- [Templates](../templates.md) - Boilerplate templates
|
||||
|
||||
### ⚙️ Modules
|
||||
|
||||
@@ -68,6 +55,7 @@ Technical references and APIs:
|
||||
|
||||
- [Functions](./reference/functions.md) - Library functions documentation
|
||||
- [Patterns](./reference/patterns.md) - Code patterns and anti-patterns
|
||||
- [Templates](../templates.md) - Boilerplate for packages and modules
|
||||
|
||||
## Repository Structure
|
||||
|
||||
|
||||
261
docs/guides/adding-modules.md
Normal file
261
docs/guides/adding-modules.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# Adding Modules Guide
|
||||
|
||||
How to add new NixOS and Home Manager modules to m3ta-nixpkgs.
|
||||
|
||||
## Overview
|
||||
|
||||
Modules extend your system or user configuration with reusable, declarative options. m3ta-nixpkgs uses the standard NixOS module system with a `m3ta.*` namespace.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Use a template for quick setup:
|
||||
|
||||
```bash
|
||||
# NixOS module
|
||||
nix flake init -t .#nixos-module my-module
|
||||
|
||||
# Home Manager module
|
||||
nix flake init -t .#home-manager-module my-module
|
||||
```
|
||||
|
||||
This copies the template into `templates/` — move it to the appropriate location and customize.
|
||||
|
||||
## Adding a NixOS Module
|
||||
|
||||
### 1. Create the Module File
|
||||
|
||||
Create `modules/nixos/<my-module>.nix`:
|
||||
|
||||
```nix
|
||||
{config, lib, pkgs, ...}:
|
||||
with lib; let
|
||||
cfg = config.m3ta.myModule;
|
||||
in {
|
||||
options.m3ta.myModule = {
|
||||
enable = mkEnableOption "my module description";
|
||||
# Add custom options here
|
||||
someOption = mkOption {
|
||||
type = types.str;
|
||||
default = "default-value";
|
||||
description = "Description of this option";
|
||||
};
|
||||
};
|
||||
|
||||
config = mkIf cfg.enable {
|
||||
# System configuration goes here
|
||||
environment.systemPackages = [pkgs.some-package];
|
||||
|
||||
# Or systemd services
|
||||
systemd.services.my-service = {
|
||||
enable = true;
|
||||
description = "My service";
|
||||
wantedBy = ["multi-user.target"];
|
||||
serviceConfig = {
|
||||
ExecStart = "${pkgs.some-package}/bin/some-daemon";
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Register in the Aggregator
|
||||
|
||||
Add to `modules/nixos/default.nix`:
|
||||
|
||||
```nix
|
||||
{
|
||||
imports = [
|
||||
./ports.nix
|
||||
./mem0.nix
|
||||
./<my-module>.nix # ← add your module
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Export from flake.nix
|
||||
|
||||
Add to the `nixosModules` output in `flake.nix` (optional, for direct import):
|
||||
|
||||
```nix
|
||||
nixosModules = {
|
||||
default = ./modules/nixos;
|
||||
ports = ./modules/nixos/ports.nix;
|
||||
mem0 = ./modules/nixos/mem0.nix;
|
||||
my-module = ./modules/nixos/<my-module>.nix; # ← add this
|
||||
};
|
||||
```
|
||||
|
||||
## Adding a Home Manager Module
|
||||
|
||||
Home Manager modules are organized by category under `modules/home-manager/`.
|
||||
|
||||
### Categories
|
||||
|
||||
| Category | Purpose | Location |
|
||||
|----------|---------|----------|
|
||||
| `cli/` | Command-line tools and utilities | `modules/home-manager/cli/` |
|
||||
| `coding/` | Development tools, editors, agents | `modules/home-manager/coding/` |
|
||||
| Root | Cross-cutting concerns (e.g., ports) | `modules/home-manager/` |
|
||||
|
||||
### 1. Choose a Category
|
||||
|
||||
- **CLI tools** (zsh plugins, tmux config, etc.) → `cli/`
|
||||
- **Development tools** (editor config, linters, etc.) → `coding/`
|
||||
- **System-wide settings** (ports, environment) → root level
|
||||
|
||||
### 2. Create the Module File
|
||||
|
||||
Create `modules/home-manager/<category>/<my-module>.nix`:
|
||||
|
||||
```nix
|
||||
{config, lib, pkgs, ...}:
|
||||
with lib; let
|
||||
cfg = config.m3ta.myModule;
|
||||
in {
|
||||
options.m3ta.myModule = {
|
||||
enable = mkEnableOption "my user module description";
|
||||
someOption = mkOption {
|
||||
type = types.str;
|
||||
default = "value";
|
||||
description = "An option for this module";
|
||||
};
|
||||
};
|
||||
|
||||
config = mkIf cfg.enable {
|
||||
home.packages = [pkgs.some-package];
|
||||
|
||||
# Or Home Manager-specific options
|
||||
programs.zsh.enable = true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Register in the Category Aggregator
|
||||
|
||||
For `cli/` modules, add to `modules/home-manager/cli/default.nix`:
|
||||
|
||||
```nix
|
||||
{
|
||||
imports = [
|
||||
./rofi-project-opener.nix
|
||||
./stt-ptt.nix
|
||||
./zellij-ps.nix
|
||||
./<my-module>.nix # ← add your module
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
For `coding/` modules, add to `modules/home-manager/coding/default.nix`:
|
||||
|
||||
```nix
|
||||
{
|
||||
imports = [
|
||||
./editors.nix
|
||||
./opencode.nix
|
||||
./agents
|
||||
./<my-module>.nix # ← add your module
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Export from flake.nix
|
||||
|
||||
Add to `homeManagerModules` in `flake.nix`:
|
||||
|
||||
```nix
|
||||
homeManagerModules = {
|
||||
default = import ./modules/home-manager;
|
||||
my-module = import ./modules/home-manager/<category>/<my-module>.nix; # ← add this
|
||||
};
|
||||
```
|
||||
|
||||
## Module Patterns
|
||||
|
||||
### Standard Enable Option
|
||||
|
||||
Always start with `mkEnableOption`:
|
||||
|
||||
```nix
|
||||
options.m3ta.myModule = {
|
||||
enable = mkEnableOption "my module";
|
||||
};
|
||||
```
|
||||
|
||||
### Conditional Configuration
|
||||
|
||||
Use `mkIf` for conditional config:
|
||||
|
||||
```nix
|
||||
config = mkIf cfg.enable {
|
||||
# Only applied when enabled
|
||||
};
|
||||
```
|
||||
|
||||
### Multiple Conditions
|
||||
|
||||
Use `mkMerge` when combining multiple conditional blocks:
|
||||
|
||||
```nix
|
||||
config = mkMerge [
|
||||
(mkIf cfg.feature1.enable { ... })
|
||||
(mkIf cfg.feature2.enable { ... })
|
||||
];
|
||||
```
|
||||
|
||||
### Nested Namespaces
|
||||
|
||||
For logically grouped options, use nested namespaces:
|
||||
|
||||
```nix
|
||||
options.m3ta.coding = {
|
||||
myTool = {
|
||||
enable = mkEnableOption "my coding tool";
|
||||
# ...
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Usage: `m3ta.coding.myTool.enable = true;`
|
||||
|
||||
### Shared Library Functions
|
||||
|
||||
For shared utilities (port helpers, etc.), import from `lib/`:
|
||||
|
||||
```nix
|
||||
let
|
||||
portsLib = import ../../lib/ports.nix {inherit lib;};
|
||||
portHelpers = portsLib.mkPortHelpers { /* ... */ };
|
||||
in {
|
||||
# use portHelpers
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Add documentation for your module:
|
||||
|
||||
1. Create `docs/modules/nixos/<my-module>.md` (NixOS) or `docs/modules/home-manager/<category>/<my-module>.md` (HM)
|
||||
2. Follow the existing format in `docs/modules/`
|
||||
3. Add it to the appropriate overview page's "Available Modules" list
|
||||
4. Link it from `docs/guides/using-modules.md`
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Validate the module loads correctly
|
||||
nix flake check
|
||||
|
||||
# Test with a minimal configuration (NixOS)
|
||||
nixos-rebuild dry-build -I nixpkgs=. --option experimental-features flakes
|
||||
|
||||
# Format before commit
|
||||
nix fmt
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [Using Modules](./using-modules.md) - How to use existing modules
|
||||
- [Port Management](./port-management.md) - Centralized port management
|
||||
- [Development Workflow](./development-workflow.md) - Local development
|
||||
- [Adding Packages](./adding-packages.md) - Adding packages (not modules)
|
||||
- [Architecture](../ARCHITECTURE.md) - Repository structure
|
||||
@@ -662,5 +662,7 @@ nix eval .#nixosConfigurations.hostname.config.m3ta --apply builtins.attrNames
|
||||
|
||||
- [Port Management](./port-management.md) - Detailed port management guide
|
||||
- [Adding Packages](./adding-packages.md) - How to add new packages
|
||||
- [Adding Modules](./adding-modules.md) - How to add new NixOS or Home Manager modules
|
||||
- [Templates](../templates.md) - Boilerplate for new packages and modules
|
||||
- [Architecture](../ARCHITECTURE.md) - Understanding module structure
|
||||
- [Contributing](../CONTRIBUTING.md) - Code style and guidelines
|
||||
|
||||
53
docs/packages/README.md
Normal file
53
docs/packages/README.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Packages
|
||||
|
||||
Documentation for packages in m3ta-nixpkgs. Each package directory may contain a `README.md` with detailed documentation.
|
||||
|
||||
## Index
|
||||
|
||||
Packages are organized in `pkgs/<name>/`. Add a `README.md` inside a package directory to document it here.
|
||||
|
||||
### Local Packages
|
||||
|
||||
These packages are built from source in `pkgs/<name>/`:
|
||||
|
||||
| Package | Description | Type | Location |
|
||||
|---------|-------------|------|----------|
|
||||
| `sidecar` | Companion tool for CLI agents with diffs, file trees, and task management | Go | `pkgs/sidecar/` |
|
||||
| `td` | Minimalist CLI for tracking tasks across AI coding sessions | Go | `pkgs/td/` |
|
||||
| `code2prompt` | Convert code to prompts | Go | `pkgs/code2prompt/` |
|
||||
| `eigent` | Eigenvalue tool | Python | `pkgs/eigent/` |
|
||||
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper | Shell | `pkgs/hyprpaper-random/` |
|
||||
| `kestractl` | CLI for Kestra workflow orchestration | Go | `pkgs/kestractl/` |
|
||||
| `launch-webapp` | Launch web applications | Shell | `pkgs/launch-webapp/` |
|
||||
| `mem0` | AI memory assistant with vector storage | Python | `pkgs/mem0/` |
|
||||
| `msty-studio` | Msty Studio application | Python | `pkgs/msty-studio/` |
|
||||
| `n8n` | Workflow automation tool | Node.js | `pkgs/n8n/` |
|
||||
| `openshell` | AI shell assistant | Go | `pkgs/openshell/` |
|
||||
| `pomodoro-timer` | Pomodoro timer utility | Shell | `pkgs/pomodoro-timer/` |
|
||||
| `rofi-project-opener` | Rofi-based project launcher | Shell | `pkgs/rofi-project-opener/` |
|
||||
| `stt-ptt` | Push to Talk Speech to Text | Python | `pkgs/stt-ptt/` |
|
||||
| `tuxedo-backlight` | Backlight control for Tuxedo laptops | C | `pkgs/tuxedo-backlight/` |
|
||||
| `vibetyper` | Typing practice tool | Python | `pkgs/vibetyper/` |
|
||||
| `zellij-ps` | Project switcher for Zellij | Rust | `pkgs/zellij-ps/` |
|
||||
|
||||
### Pass-Through Packages
|
||||
|
||||
These packages are imported directly from flake inputs with minor modifications:
|
||||
|
||||
| Package | Source | Modification | Location |
|
||||
|---------|--------|-------------|----------|
|
||||
| `opencode-desktop` | `inputs.opencode` | Tauri desktop wrapper + Wayland fix | `pkgs/opencode-desktop/` |
|
||||
|
||||
## Adding Package Documentation
|
||||
|
||||
To document a package in detail, add a `README.md` inside the package directory (e.g., `pkgs/sidecar/README.md`). This guide indexes all packages and provides a quick overview.
|
||||
|
||||
## Automated Updates
|
||||
|
||||
Packages are automatically updated weekly by the Gitea Actions `nix-update` workflow. See the main README for details.
|
||||
|
||||
## Related
|
||||
|
||||
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
|
||||
- [Architecture](../ARCHITECTURE.md) - Repository structure
|
||||
- [Quick Start](../QUICKSTART.md) - Getting started
|
||||
@@ -153,33 +153,6 @@ allServices = portHelpers.listServices;
|
||||
# Returns: ["nginx" "grafana" "prometheus" "homepage"]
|
||||
```
|
||||
|
||||
### `getDefaultPort`
|
||||
|
||||
Simple helper to get a port without host override.
|
||||
|
||||
#### Signature
|
||||
|
||||
```nix
|
||||
getDefaultPort :: portsConfig -> string -> int-or-null
|
||||
```
|
||||
|
||||
#### Arguments
|
||||
|
||||
1. `portsConfig` - Same structure as `mkPortHelpers`
|
||||
2. `service` - The service name (string)
|
||||
|
||||
#### Returns
|
||||
|
||||
Port number (int) or `null` if service not found.
|
||||
|
||||
#### Usage
|
||||
|
||||
```nix
|
||||
services.my-service = {
|
||||
port = m3taLib.ports.getDefaultPort myPorts "my-service";
|
||||
};
|
||||
```
|
||||
|
||||
## Using Library Functions
|
||||
|
||||
### Importing
|
||||
@@ -262,7 +235,7 @@ in {
|
||||
| `getPort` | Get port with optional host override | `int or null` |
|
||||
| `getHostPorts` | Get all ports for host | `attrs` |
|
||||
| `listServices` | List all service names | `[string]` |
|
||||
| `getDefaultPort` | Get default port only | `int or null` |
|
||||
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
162
docs/templates.md
Normal file
162
docs/templates.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Templates
|
||||
|
||||
Boilerplate templates for quickly adding new packages or modules to m3ta-nixpkgs.
|
||||
|
||||
## Available Templates
|
||||
|
||||
| Template | Command | Creates |
|
||||
|---------|---------|---------|
|
||||
| Package | `nix flake init -t .#package` | `templates/package/` |
|
||||
| NixOS Module | `nix flake init -t .#nixos-module` | `templates/nixos-module/` |
|
||||
| Home Manager Module | `nix flake init -t .#home-manager-module` | `templates/home-manager-module/` |
|
||||
|
||||
## Using Templates
|
||||
|
||||
### 1. List Available Templates
|
||||
|
||||
```bash
|
||||
nix flake show --templates .
|
||||
```
|
||||
|
||||
### 2. Initialize from a Template
|
||||
|
||||
```bash
|
||||
# Package
|
||||
nix flake init -t .#package
|
||||
|
||||
# NixOS Module
|
||||
nix flake init -t .#nixos-module
|
||||
|
||||
# Home Manager Module
|
||||
nix flake init -t .#home-manager-module
|
||||
```
|
||||
|
||||
Note: `nix flake init` copies the template contents into the current directory. Use a subdirectory name:
|
||||
|
||||
```bash
|
||||
mkdir new-package && cd new-package
|
||||
nix flake init -t ..#package
|
||||
```
|
||||
|
||||
## Package Template
|
||||
|
||||
Creates a complete package structure:
|
||||
|
||||
```
|
||||
templates/package/
|
||||
├── default.nix # Package definition with comments
|
||||
```
|
||||
|
||||
### Fields to Fill In
|
||||
|
||||
| Field | Location | Notes |
|
||||
|-------|----------|-------|
|
||||
| `pname` | `default.nix` | Package name (kebab-case) |
|
||||
| `version` | `default.nix` | Semantic version |
|
||||
| `src` | `default.nix` | Fetcher (GitHub, URL, Git, etc.) |
|
||||
| `hash` | `default.nix` | Use `lib.fakeHash`, build to get real hash |
|
||||
| `meta.description` | `default.nix` | Short one-line description |
|
||||
| `meta.homepage` | `default.nix` | Project URL |
|
||||
| `meta.license` | `default.nix` | Use `lib.licenses.*` |
|
||||
| `meta.platforms` | `default.nix` | Usually `platforms.linux` |
|
||||
| `meta.mainProgram` | `default.nix` | Main binary name |
|
||||
|
||||
### Common Build Systems
|
||||
|
||||
```nix
|
||||
# Rust (recommended)
|
||||
rustPlatform.buildRustPackage rec { ... }
|
||||
|
||||
# Python
|
||||
python3.pkgs.buildPythonPackage rec { ... }
|
||||
|
||||
# Node.js
|
||||
pkg-config, nodejs, npm2nix, or pnpm + prisma
|
||||
|
||||
# Shell script
|
||||
writeShellScriptBin "name" ''echo hello''
|
||||
|
||||
# Go
|
||||
go mdbook build
|
||||
|
||||
# Generic C/Make
|
||||
stdenv.mkDerivation { ... }
|
||||
```
|
||||
|
||||
See [Adding Packages](./guides/adding-packages.md) for detailed instructions.
|
||||
|
||||
## NixOS Module Template
|
||||
|
||||
Creates a complete NixOS module:
|
||||
|
||||
```
|
||||
templates/nixos-module/
|
||||
├── default.nix # Module with options
|
||||
└── README.md # Module documentation
|
||||
```
|
||||
|
||||
### Fields to Fill In
|
||||
|
||||
| Field | Location | Notes |
|
||||
|-------|----------|-------|
|
||||
| Module name | `default.nix` | File name matches `m3ta.<name>` |
|
||||
| Options | `default.nix` | Add under `options.m3ta.<name>` |
|
||||
| Config | `default.nix` | Add under `config.m3ta.<name>` |
|
||||
| Description | `README.md` | What the module does |
|
||||
|
||||
### After Creating
|
||||
|
||||
1. Add to `modules/nixos/default.nix` imports
|
||||
2. Optionally export from `flake.nix` `nixosModules`
|
||||
3. Add documentation to `docs/modules/nixos/`
|
||||
4. Run `nix flake check`
|
||||
|
||||
## Home Manager Module Template
|
||||
|
||||
Creates a complete Home Manager module:
|
||||
|
||||
```
|
||||
templates/home-manager-module/
|
||||
├── default.nix # Module with options
|
||||
└── README.md # Module documentation
|
||||
```
|
||||
|
||||
### Fields to Fill In
|
||||
|
||||
| Field | Location | Notes |
|
||||
|-------|----------|-------|
|
||||
| Category | Directory | Choose `cli/` or `coding/` |
|
||||
| Options | `default.nix` | Add under `options.m3ta.<name>` |
|
||||
| Config | `default.nix` | Add under `config.m3ta.<name>` |
|
||||
| Description | `README.md` | What the module does |
|
||||
|
||||
### After Creating
|
||||
|
||||
1. Add to the appropriate category aggregator (`cli/default.nix` or `coding/default.nix`)
|
||||
2. Optionally export from `flake.nix` `homeManagerModules`
|
||||
3. Add documentation to `docs/modules/home-manager/`
|
||||
4. Run `nix flake check`
|
||||
|
||||
## Template Variables
|
||||
|
||||
Templates use Nix attribute references. After copying, search for these placeholders:
|
||||
|
||||
| Placeholder | Replace With |
|
||||
|-------------|--------------|
|
||||
| `package-name` | Your package name (kebab-case) |
|
||||
| `owner-name` / `repo-name` | GitHub owner and repo |
|
||||
| `0.1.0` | Initial version |
|
||||
| `lib.fakeHash` | Real hash after first build |
|
||||
| `lib.licenses.mit` | Appropriate license |
|
||||
| `A short description` | One-line description |
|
||||
|
||||
## Automated Updates
|
||||
|
||||
Packages created from templates are automatically updated weekly by the Gitea Actions workflow. See the main README for details on the `nix-update` automation.
|
||||
|
||||
## Related
|
||||
|
||||
- [Adding Packages](./guides/adding-packages.md) - Detailed package guide
|
||||
- [Adding Modules](./guides/adding-modules.md) - Detailed module guide
|
||||
- [Development Workflow](./guides/development-workflow.md) - Local development
|
||||
- [Architecture](./ARCHITECTURE.md) - Repository structure
|
||||
Reference in New Issue
Block a user