nixpkgs/QUICKSTART.md

# Quick Start Guide

Get started with m3ta-nixpkgs in 5 minutes! This guide covers the most common use cases.

## Prerequisites

Ensure Nix flakes are enabled:

```bash
# Add to ~/.config/nix/nix.conf or /etc/nix/nix.conf
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
```

## Quick Usage

### 1. Try a Package Without Installing

```bash
# Run a package directly
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt

# Try it in a temporary shell
nix shell git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
```

### 2. Install to Your Profile

```bash
# Install a package
nix profile install git+https://code.m3ta.dev/m3tam3re/nixpkgs#msty-studio

# List installed packages
nix profile list

# Remove a package
nix profile remove <index>
```

### 3. Add to Your NixOS Configuration

Edit your `flake.nix`:

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
  };

  outputs = {nixpkgs, m3ta-nixpkgs, ...}: {
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      modules = [
        {
          nixpkgs.overlays = [m3ta-nixpkgs.overlays.default];

          environment.systemPackages = with pkgs; [
            code2prompt
            hyprpaper-random
            zellij-ps
          ];
        }
      ];
    };
  };
}
```

Then rebuild:

```bash
sudo nixos-rebuild switch --flake .#yourhostname
```

### 4. Add to Home Manager (Standalone)

Edit your Home Manager `flake.nix`:

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
  };

  outputs = {nixpkgs, home-manager, m3ta-nixpkgs, ...}: {
    homeConfigurations.m3tam3re = home-manager.lib.homeManagerConfiguration {
      pkgs = import nixpkgs {
        system = "x86_64-linux";
        overlays = [m3ta-nixpkgs.overlays.default];
      };

      modules = [
        {
          home.packages = with pkgs; [
            code2prompt
            pomodoro-timer
          ];
        }
      ];
    };
  };
}
```

Then activate:

```bash
home-manager switch --flake .#m3tam3re
```

### 5. Use During Development (Local Path)

When working on your system configuration:

```nix
{
  inputs = {
    # Use local path during development
    m3ta-nixpkgs.url = "path:/home/you/projects/m3ta-nixpkgs";
    # Or use git+file for uncommitted changes
    # m3ta-nixpkgs.url = "git+file:///home/you/projects/m3ta-nixpkgs";
  };
}
```

## Available Packages

| Package            | Description                     | Command                      |
| ------------------ | ------------------------------- | ---------------------------- |
| `code2prompt`      | Convert code to LLM prompts     | `nix run .#code2prompt`      |
| `hyprpaper-random` | Random wallpaper for Hyprpaper  | `nix run .#hyprpaper-random` |
| `launch-webapp`    | Launch web applications         | `nix run .#launch-webapp`    |
| `msty-studio`      | Msty Studio application         | `nix run .#msty-studio`      |
| `pomodoro-timer`   | Pomodoro timer utility          | `nix run .#pomodoro-timer`   |
| `tuxedo-backlight` | Tuxedo laptop backlight control | `nix run .#tuxedo-backlight` |
| `zellij-ps`        | Process viewer for Zellij       | `nix run .#zellij-ps`        |

## Common Commands

```bash
# Show all available packages
nix flake show git+https://code.m3ta.dev/m3tam3re/nixpkgs

# Update the flake lock file
nix flake update

# Build a specific package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt

# Check flake validity
nix flake check git+https://code.m3ta.dev/m3tam3re/nixpkgs
```

## Development Workflow

### Adding Your Own Package

1. **Clone the repo:**

   ```bash
   git clone https://code.m3ta.dev/m3tam3re/nixpkgs
   cd m3ta-nixpkgs
   ```

2. **Create package directory:**

   ```bash
   mkdir pkgs/my-package
   cp templates/package/default.nix pkgs/my-package/
   ```

3. **Edit `pkgs/my-package/default.nix`** with your package details

4. **Register in `pkgs/default.nix`:**

   ```nix
   {pkgs, ...}: {
     # ... existing packages ...
     my-package = pkgs.callPackage ./my-package {};
   }
   ```

5. **Test it:**

   ```bash
   git add -A  # Nix flakes require git tracking
   nix build .#my-package
   ```

6. **Commit and push:**
   ```bash
   git commit -m "feat: add my-package"
   git push
   ```

## Troubleshooting

### Issue: "experimental-features" error

**Solution:** Enable flakes in nix.conf (see Prerequisites)

### Issue: "path is not tracked by Git"

**Solution:** `git add` your files before running Nix commands

### Issue: Package fails to build

**Solution:**

```bash
# Check build logs
nix build .#package-name --show-trace

# Try with fresh build
nix build .#package-name --rebuild
```

### Issue: Hash mismatch

**Solution:** Use `lib.fakeHash` first, then replace with the correct hash from the error message

## Next Steps

- 📖 Read the full [README.md](README.md) for detailed documentation
- 🤝 Check [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines
- 💡 Browse [examples/](examples/) for more configuration examples
- 🔍 Explore the [templates/](templates/) for creating new packages and modules

## Getting Help

- 💬 [NixOS Discourse](https://discourse.nixos.org/)
- 💭 [NixOS Matrix Chat](https://matrix.to/#/#nix:nixos.org)
- 📚 [Nix Pills](https://nixos.org/guides/nix-pills/)
- 📖 [Nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/)

---

**Ready to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md) to get started!