first
This commit is contained in:
m3tam3re
240
QUICKSTART.md
Normal file
240
QUICKSTART.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user