291 lines
7.0 KiB
Markdown
291 lines
7.0 KiB
Markdown
# 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";
|
|
};
|
|
}
|
|
```
|
|
|
|
### 6. Use Library Functions
|
|
|
|
The repository includes helper functions for common configuration tasks.
|
|
|
|
#### Port Management Example
|
|
|
|
```nix
|
|
{
|
|
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
|
|
|
|
```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!
|