# Installation Guide

## First-Time Setup

### On macOS

#### 1. Install Nix (if not already installed)

```bash
sh <(curl -L https://nixos.org/nix/install)
```

#### 2. Enable Flakes

Create or edit `~/.config/nix/nix.conf`:

```bash
mkdir -p ~/.config/nix
cat <<EOF > ~/.config/nix/nix.conf
experimental-features = nix-command flakes
EOF
```

Restart your terminal or run:
```bash
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
```

#### 3. Configure Your System

Edit the following files:

**In `flake.nix`:**
- Line 82-97: Replace `your-hostname` with your actual hostname (run `hostname` to find it)
- Line 94: Replace `your-username` with your actual username (run `whoami`)

**In `darwin/configuration.nix`:**
- Line 33-34: Set your hostname
- Line 45: Set your architecture:
  - Apple Silicon (M1/M2/M3): `"aarch64-darwin"`
  - Intel: `"x86_64-darwin"`
- Line 48-51: Set your username

**In `home-manager/home.nix`:**
- Line 30: Set your username

**In `home-manager/development.nix`** (optional):
- Uncomment lines for your git name and email

#### 4. Build and Apply

```bash
# Build the darwin configuration (first time)
nix build .#darwinConfigurations.YOUR-HOSTNAME.system --extra-experimental-features "nix-command flakes"

# Apply it
./result/sw/bin/darwin-rebuild switch --flake .#YOUR-HOSTNAME
```

After the first successful build, you can use:
```bash
darwin-rebuild switch --flake .#YOUR-HOSTNAME
```

#### 5. Reload Your Shell

Close and reopen your terminal, or source your shell config:
```bash
# For zsh:
source ~/.zshrc

# For fish:
source ~/.config/fish/config.fish

# For bash:
source ~/.bashrc
```

### On NixOS

#### 1. Clone This Repository

```bash
# As root or with sudo
cd /etc/nixos
git clone <your-repo-url> .
# Or copy your files to /etc/nixos
```

#### 2. Configure Your System

Edit the following files:

**In `flake.nix`:**
- Line 59-75: Replace `your-hostname` with your actual hostname
- Line 72: Replace `your-username` with your actual username

**In `nixos/configuration.nix`:**
- Line 38: Set your hostname
- Line 43-54: Configure your user account
- Uncomment line 47-51 if you want to set an initial password

**In `home-manager/home.nix`:**
- Line 30: Set your username

**In `home-manager/development.nix`** (optional):
- Uncomment lines for your git name and email

#### 3. Generate Hardware Configuration

If you haven't already:
```bash
sudo nixos-generate-config --show-hardware-config > nixos/hardware-configuration.nix
```

#### 4. Build and Apply

```bash
sudo nixos-rebuild switch --flake .#YOUR-HOSTNAME
```

#### 5. Reboot (optional but recommended)

```bash
sudo reboot
```

## Updating Your Configuration

### Update Flake Inputs (packages)

```bash
nix flake update
```

Then rebuild:
```bash
# macOS:
darwin-rebuild switch --flake .#YOUR-HOSTNAME

# NixOS:
sudo nixos-rebuild switch --flake .#YOUR-HOSTNAME
```

### Making Configuration Changes

1. Edit the relevant configuration files
2. Rebuild and switch:

```bash
# macOS:
darwin-rebuild switch --flake .

# NixOS:
sudo nixos-rebuild switch --flake .
```

### Testing Changes Before Applying

```bash
# macOS:
darwin-rebuild build --flake .

# NixOS:
sudo nixos-rebuild build --flake .
```

If the build succeeds, you can then apply with `switch`.

## Common Customizations

### Add User Packages

Edit `home-manager/common.nix`, `home-manager/development.nix`, or the platform-specific files:

```nix
home.packages = with pkgs; [
  firefox
  vscode
  ripgrep
];
```

### Enable a Program

Most programs can be enabled via home-manager options:

```nix
programs.firefox.enable = true;
programs.git = {
  enable = true;
  userName = "Your Name";
  userEmail = "you@example.com";
};
```

### Add System Packages

Edit `common.nix` or the platform-specific configuration:

```nix
environment.systemPackages = with pkgs; [
  vim
  wget
  curl
];
```

### Customize Shell

Edit `home-manager/shell.nix` to configure bash, zsh, fish, or starship prompt.

### macOS System Defaults

Edit `darwin/configuration.nix` to customize macOS behavior (Dock, Finder, keyboard, etc.).

## Troubleshooting

### Build Fails with "experimental Nix feature 'flakes' is disabled"

Make sure you've enabled flakes in `~/.config/nix/nix.conf`:
```
experimental-features = nix-command flakes
```

### "error: collision between..." 

This means two packages are trying to install the same files. Check for:
- Duplicate packages in system and home-manager configs
- Conflicting package versions

### macOS: "Could not find nix-darwin"

On first install, you need to build with the full path:
```bash
nix build .#darwinConfigurations.YOUR-HOSTNAME.system
./result/sw/bin/darwin-rebuild switch --flake .
```

### Home Manager File Conflicts

If home-manager tries to manage files that already exist, back them up:
```bash
# Create backups of existing files
for file in ~/.bashrc ~/.zshrc ~/.config/fish/config.fish; do
  [ -f "$file" ] && mv "$file" "$file.backup"
done
```

Or use the backup flag:
```bash
home-manager switch --flake . --backup-extension .backup
```

### Can't Find Your Hostname

```bash
# macOS and Linux:
hostname

# If it's not what you expect, you can change it:
# macOS (temporarily):
sudo scutil --set HostName your-new-hostname

# NixOS: Set in configuration.nix
```

### Rollback to Previous Generation

If a new configuration breaks something:

```bash
# macOS:
darwin-rebuild --rollback

# NixOS:
sudo nixos-rebuild --rollback
```

## Next Steps

After installation:

1. **Customize your configuration** - Edit the home-manager modules to suit your workflow
2. **Add your development tools** - Uncomment languages/tools you need in `development.nix`
3. **Configure Git** - Set your name and email in `development.nix`
4. **Set up shell** - Choose your preferred shell and customize in `shell.nix`
5. **Explore options** - Check out [Home Manager options](https://nix-community.github.io/home-manager/options.html)

## Getting Help

- [NixOS Discourse](https://discourse.nixos.org/)
- [Nix Discord](https://discord.gg/RbvHtGa)
- [r/NixOS](https://www.reddit.com/r/NixOS/)
- [Nix Documentation](https://nixos.org/learn.html)