250 lines
7.1 KiB
Markdown
250 lines
7.1 KiB
Markdown
# 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
|
|
|