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:

# 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

# 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

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

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

sudo nixos-rebuild switch --flake .#yourhostname

4. Add to Home Manager (Standalone)

Edit your Home Manager flake.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:

home-manager switch --flake .#m3tam3re

5. Use During Development (Local Path)

When working on your system configuration:

{
  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";
  };
}

6. Use Library Functions

The repository includes helper functions for common configuration tasks.

Port Management Example

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

  outputs = {nixpkgs, m3ta-nixpkgs, ...}: {
    nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = {inherit inputs; system = "x86_64-linux";};
      modules = [
        ({inputs, system, config, ...}: let
          # Import the library
          m3taLib = inputs.m3ta-nixpkgs.lib.${system};

          # Define all your ports centrally
          myPorts = {
            ports = {
              nginx = 80;
              grafana = 3000;
              prometheus = 9090;
            };
            hostPorts = {
              laptop = {nginx = 8080;}; # Override on laptop
            };
          };

          # Create port helpers
          ports = m3taLib.ports.mkPortHelpers myPorts;
          hostname = config.networking.hostName;
        in {
          # Use in configuration
          services.nginx.defaultHTTPListenPort = ports.getPort "nginx" hostname;
          services.grafana.settings.server.http_port = ports.getPort "grafana" hostname;
        })
      ];
    };
  };
}

See examples/ports-example.nix for more examples and lib/README.md for full documentation.

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

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

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

2. Create package directory:

   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:

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

5. Test it:

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

6. Commit and push:

   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:

# 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 for detailed documentation
• 🤝 Check CONTRIBUTING.md for development guidelines
• 💡 Browse examples/ for more configuration examples
• 🔍 Explore the templates/ for creating new packages and modules

Getting Help

• 💬 NixOS Discourse
• 💭 NixOS Matrix Chat
• 📚 Nix Pills
• 📖 Nixpkgs Manual

---

Ready to contribute? See CONTRIBUTING.md to get started!