# Cross-Platform Nix Configuration

A modular Nix configuration that works on both macOS (via nix-darwin) and Linux (NixOS), with maximum config sharing through home-manager.

## Structure

```
├── flake.nix                    # Main flake configuration
├── common.nix                   # Shared system-level config (NixOS & nix-darwin)
│
├── darwin/                      # macOS system configuration
│   └── configuration.nix
│
├── nixos/                       # NixOS system configuration
│   ├── configuration.nix
│   └── hardware-configuration.nix
│
├── home-manager/                # User environment (shared across platforms)
│   ├── home.nix                 # Main home-manager config
│   ├── common.nix               # Base configuration
│   ├── development.nix          # Development tools
│   ├── shell.nix                # Shell configuration
│   ├── terminal.nix             # Terminal apps & utilities
│   ├── linux.nix                # Linux-specific overrides
│   └── darwin.nix               # macOS-specific overrides
│
├── modules/
│   ├── home-manager/            # Shared home-manager modules
│   ├── nixos/                   # NixOS-specific modules
│   └── darwin/                  # nix-darwin-specific modules
│
├── overlays/                    # Package overlays
│   └── default.nix
│
└── pkgs/                        # Custom packages
    └── default.nix
```

## Getting Started

### Prerequisites

**On macOS:**
1. Install Nix: `sh <(curl -L https://nixos.org/nix/install)`
2. Enable flakes by adding to `~/.config/nix/nix.conf`:
   ```
   experimental-features = nix-command flakes
   ```

**On NixOS:**
Flakes should be enabled via this configuration.

### Configuration Steps

1. **Update your username and hostname:**
   - In `flake.nix`: Replace `your-username` and `your-hostname` in the configurations
   - In `home-manager/home.nix`: Update the username
   - In `darwin/configuration.nix` or `nixos/configuration.nix`: Update hostname and user settings

2. **Set your architecture** (macOS):
   - In `darwin/configuration.nix`, set `nixpkgs.hostPlatform` to either:
     - `"aarch64-darwin"` (Apple Silicon)
     - `"x86_64-darwin"` (Intel)

3. **Configure Git identity** (optional):
   - In `home-manager/development.nix`, uncomment and set:
     ```nix
     userName = "Your Name";
     userEmail = "your.email@example.com";
     ```

### Building & Activating

**On macOS (first time):**
```bash
# Build the darwin configuration
nix build .#darwinConfigurations.your-hostname.system

# Activate it
./result/sw/bin/darwin-rebuild switch --flake .#your-hostname
```

**On macOS (subsequent builds):**
```bash
darwin-rebuild switch --flake .#your-hostname
```

**On NixOS:**
```bash
sudo nixos-rebuild switch --flake .#your-hostname
```

**Standalone home-manager** (if not using system integration):
```bash
home-manager switch --flake .#your-username@your-hostname
```

## Key Features

### Platform-Aware Configuration

The configuration automatically detects the platform using `pkgs.stdenv.isDarwin` and `pkgs.stdenv.isLinux`:

- Home directory: Automatically uses `/Users/` on macOS, `/home/` on Linux
- Platform-specific packages and services are conditionally enabled
- Shared configuration in `common.nix` for consistent experience

### Modular Home-Manager

Your user environment is split into logical modules:

- **common.nix**: Basic tools everyone needs (git, ripgrep, etc.)
- **development.nix**: Development tools (languages, IDEs, etc.)
- **shell.nix**: Shell configuration (bash, zsh, fish, starship)
- **terminal.nix**: Terminal applications (tmux, neovim, alacritty)
- **linux.nix**: Linux-specific GUI apps and services
- **darwin.nix**: macOS-specific apps and integrations

### Shared System Configuration

`common.nix` is imported by both NixOS and nix-darwin configurations, providing:

- Unified Nix settings (flakes, garbage collection, etc.)
- Shared package overlays
- Consistent nixpkgs configuration

### Easy to Extend

- Add new home-manager modules in `modules/home-manager/`
- Add platform-specific modules in `modules/nixos/` or `modules/darwin/`
- Add custom packages in `pkgs/`
- Add overlays in `overlays/`

## Customization Tips

### Adding Packages

**User packages** (home-manager):
Add to the appropriate module:
- `home-manager/common.nix` for shared packages
- `home-manager/linux.nix` for Linux-only
- `home-manager/darwin.nix` for macOS-only
- `home-manager/development.nix` for dev tools

**System packages**:
Add to `common.nix` for shared system packages, or to the platform-specific config.

### Enabling Programs

Most programs can be enabled via home-manager:

```nix
programs.firefox.enable = true;
programs.vscode.enable = true;
```

Check [home-manager options](https://nix-community.github.io/home-manager/options.html) for available programs.

### Multiple Machines

Add more configurations in `flake.nix`:

```nix
darwinConfigurations = {
  macbook = darwin.lib.darwinSystem { ... };
  mac-mini = darwin.lib.darwinSystem { ... };
};

nixosConfigurations = {
  desktop = nixpkgs.lib.nixosSystem { ... };
  laptop = nixpkgs.lib.nixosSystem { ... };
};
```

### macOS System Defaults

The darwin configuration includes sensible defaults for macOS. Customize in `darwin/configuration.nix`:

- Dock behavior
- Finder settings
- Keyboard settings
- Global domain defaults

## Maintenance

**Update flake inputs:**
```bash
nix flake update
```

**Garbage collect old generations:**
```bash
# This happens automatically every 7 days, but you can run manually:
nix-collect-garbage -d

# On NixOS:
sudo nix-collect-garbage -d
```

**View generations:**
```bash
# On macOS:
darwin-rebuild --list-generations

# On NixOS:
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
```

**Rollback to previous generation:**
```bash
# On macOS:
darwin-rebuild --rollback

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

## Resources

- [Nix Documentation](https://nixos.org/manual/nix/stable/)
- [NixOS Options Search](https://search.nixos.org/options)
- [Home Manager Options](https://nix-community.github.io/home-manager/options.html)
- [nix-darwin Options](https://daiderd.com/nix-darwin/manual/index.html)
- [Nix Language Basics](https://nixos.org/manual/nix/stable/language/)

## Troubleshooting

**"error: experimental Nix feature 'flakes' is disabled"**
- Enable flakes in your nix configuration

**Build fails on macOS**
- Ensure nix-darwin is properly installed
- Check that your architecture is set correctly in `darwin/configuration.nix`

**Home manager conflicts**
- If you have existing dotfiles, back them up before applying home-manager
- Use `home-manager switch --backup-extension .backup` to preserve existing files

**"collision between" errors**
- Usually means packages are providing the same files
- Check for duplicate package installations in system vs home-manager

## Contributing

Feel free to customize this configuration to your needs! The modular structure makes it easy to:
- Add new feature modules
- Share modules between machines
- Contribute modules back to the community