# Gentoo Install Preparation

## 1. Hardware Inventory

Run these on the target machine before starting. Save the output files in this directory.

```bash
lspci -vnn > hw-lspci.txt
lsusb -v > hw-lsusb.txt
cat /proc/cpuinfo > hw-cpu.txt
lsmod > hw-modules.txt
lsblk -f > hw-disks.txt
ip link show > hw-net.txt
rfkill list > hw-rfkill.txt
dmidecode -t memory > hw-ram.txt   # sudo
dmidecode -t bios > hw-bios.txt    # sudo
```

The `lspci -vnn` output is the most important. Every line maps to a kernel driver and potentially a USE flag. The `[XXXX:XXXX]` vendor:device IDs let you look up exact driver requirements.

---

## 2. Profile Selection

Profiles set hundreds of default USE flags. Pick before writing make.conf since global USE flags layer on top.

Available profiles (amd64): https://wiki.gentoo.org/wiki/Profile_(Portage)

| Profile | When to use |
|---------|-------------|
| `default/linux/amd64/23.0` | Minimal base, build everything yourself |
| `default/linux/amd64/23.0/desktop` | Generic desktop defaults |
| `default/linux/amd64/23.0/desktop/plasma` | KDE Plasma |
| `default/linux/amd64/23.0/desktop/gnome/systemd` | GNOME (requires systemd) |
| `default/linux/amd64/23.0/no-multilib` | 64-bit only, no 32-bit compat |

For a suckless/minimal setup: use the base `23.0` profile or `23.0/desktop` at most. Desktop profiles pull in flags for full DE stacks you won't use.

```bash
# List available profiles
eselect profile list

# Set profile
eselect profile set <number>
```

---

## 3. Partition Scheme

Decide before booting the live environment.

### UEFI + GPT (recommended)

| Partition | Filesystem | Size | Mount | Notes |
|-----------|-----------|------|-------|-------|
| /dev/sdX1 | FAT32 | 1G | /boot/efi | EFI System Partition |
| /dev/sdX2 | swap | = RAM | swap | Or skip if using zram |
| /dev/sdX3 | ext4 | 40-60G | / | Root |
| /dev/sdX4 | ext4 | remainder | /home | User data |

### BIOS + MBR (legacy)

| Partition | Filesystem | Size | Mount | Notes |
|-----------|-----------|------|-------|-------|
| /dev/sdX1 | ext2 | 512M | /boot | Boot partition |
| /dev/sdX2 | swap | = RAM | swap | |
| /dev/sdX3 | ext4 | 40-60G | / | Root |
| /dev/sdX4 | ext4 | remainder | /home | |

### Decisions to make

- **Encryption**: LUKS on root and/or home? Adds complexity but worth it for laptops.
- **LVM**: Flexible resizing later. Adds a layer. Usually worth it.
- **btrfs vs ext4 vs xfs**: btrfs gives snapshots and compression. ext4 is proven and simple. xfs for large files/performance.
- **Swap**: Physical partition, swap file, zram, or none. zram compresses in RAM and avoids disk I/O.
- **Separate /var or /tmp**: Usually not needed unless you have specific disk isolation requirements.

---

## 4. Global USE Flags

These go in `make.conf`. The goal is to set sensible defaults globally, then override per-package in `/etc/portage/package.use/`.

### Strategy

1. Start minimal (deny most things)
2. Add what you actually use
3. Use per-package overrides for exceptions

### Flag Categories

#### Display and Graphics

| Flag | Purpose | Enable if |
|------|---------|-----------|
| `X` | X11 support | Using X.org (yes for suckless) |
| `-wayland` | Wayland support | Not using Wayland |
| `opengl` | OpenGL support | Almost always yes |
| `vulkan` | Vulkan API | Gaming, GPU compute |
| `egl` | EGL interface | Modern GL apps |

#### Audio and Media

| Flag | Purpose | Enable if |
|------|---------|-----------|
| `pipewire` | PipeWire audio | Modern audio stack |
| `pulseaudio` | PulseAudio | Legacy; PipeWire replaces this |
| `alsa` | ALSA direct | Always, it's the kernel layer |
| `ffmpeg` | FFmpeg codecs | Media playback |
| `mp3 flac opus vorbis` | Audio codecs | As needed |
| `jpeg png webp svg` | Image formats | Almost always |

#### System and Init

| Flag | Purpose | Enable if |
|------|---------|-----------|
| `systemd` | systemd init | Using systemd |
| `-systemd` + `elogind` | OpenRC init | Using OpenRC (traditional Gentoo) |
| `dbus` | D-Bus IPC | Most desktop apps need it |
| `pam` | Auth modules | Almost always |
| `udev` | Device manager | Always |
| `policykit` | Privilege escalation | If using polkit for sudo-like GUI actions |

#### Networking

| Flag | Purpose | Enable if |
|------|---------|-----------|
| `ssl` | SSL/TLS | Always |
| `gnutls` | GnuTLS library | Some apps prefer this over OpenSSL |
| `curl` | libcurl support | Almost always |
| `wifi` | Wireless | Laptops |
| `bluetooth` | Bluetooth | If hardware present |
| `networkmanager` | NetworkManager | If using NM; skip for wpa_supplicant+dhcpcd |

#### Security

| Flag | Purpose | Enable if |
|------|---------|-----------|
| `hardened` | Security hardening | Security-focused build |
| `seccomp` | Syscall filtering | Containers, sandboxing |
| `caps` | POSIX capabilities | Fine-grained perms |

#### Development

| Flag | Purpose | Enable if |
|------|---------|-----------|
| `python` | Python bindings | Dev work |
| `-doc` | Documentation | Saves compile time if you use online docs |
| `-test` | Test suites | Don't run tests during install |

#### Shell and Completions

| Flag | Purpose | Enable if |
|------|---------|-----------|
| `fish-completion` | Fish completions | Using fish shell |
| `-bash-completion` | Bash completions | Not using bash interactively |
| `-zsh-completion` | Zsh completions | Not using zsh |
| `man` | Man pages | Yes |

### Full USE flag reference

Browse all flags: https://www.gentoo.org/support/use-flags/

Per-package flags: https://packages.gentoo.org (search package, check USE tab)

---

## 5. VIDEO_CARDS and INPUT_DEVICES

### VIDEO_CARDS

| Value | Hardware |
|-------|----------|
| `amdgpu` | AMD Radeon RX 400+ (GCN 4+) |
| `radeonsi` | AMD Radeon HD 7000+ (GCN 1-3) |
| `intel` | Intel integrated (i915/xe) |
| `nvidia` | NVIDIA proprietary driver |
| `nouveau` | NVIDIA open-source driver |
| `virgl` | VirtIO GPU (VMs) |

Set only what your hardware has. Multiple values separated by spaces.

### INPUT_DEVICES

```
INPUT_DEVICES="libinput"
```

`libinput` covers keyboards, mice, touchpads, tablets. This is the modern default. Only add `synaptics` if you specifically need it for an old touchpad.

---

## 6. Kernel Configuration

### Approach 1: Manual (maximum control)

```bash
cd /usr/src/linux
make menuconfig
```

Map your `lspci -vnn` output to kernel options. Key areas:

| Hardware | Kernel config path |
|----------|-------------------|
| CPU | Processor type and features |
| GPU | Device Drivers > Graphics support |
| NIC (ethernet) | Device Drivers > Network device support > Ethernet |
| WiFi | Device Drivers > Network device support > Wireless |
| Storage (NVMe) | Device Drivers > NVM Express block device |
| Storage (SATA) | Device Drivers > Serial ATA and PATA |
| USB | Device Drivers > USB support |
| Sound | Device Drivers > Sound card support > ALSA |
| Bluetooth | Networking support > Bluetooth |
| Filesystem | File systems (enable ext4, FAT, etc.) |

Critical: If a driver is built-in (`*`) vs module (`M`):
- Built-in: available at boot, no initramfs needed for that driver
- Module: loaded on demand, needs initramfs if required at boot (root fs driver, etc.)

### Approach 2: genkernel (automatic)

```bash
emerge sys-kernel/genkernel
genkernel all
```

Builds a kitchen-sink kernel with most drivers as modules. Works but bloated.

### Approach 3: Distribution kernel

```bash
emerge sys-kernel/gentoo-kernel-bin   # prebuilt binary
# or
emerge sys-kernel/gentoo-kernel       # builds from source with default config
```

Easiest path. You can switch to manual later.

### Pre-planning kernel config

Before install, make a checklist from your `lspci` output:

```
[ ] GPU: AMD/Intel/NVIDIA -- driver name
[ ] NIC: Realtek/Intel/Broadcom -- driver name
[ ] WiFi: Intel/Atheros/Broadcom -- driver name + firmware
[ ] Audio: Intel HDA / USB -- codec
[ ] NVMe/SATA controller
[ ] USB 3.x/Thunderbolt
[ ] Bluetooth chipset
[ ] Webcam (UVC)
[ ] Card reader
[ ] TPM (if present)
```

For each, find the kernel config option via the Gentoo wiki hardware page or `grep -r "VENDOR_ID" /usr/src/linux/`.

---

## 7. Firmware

Many devices need firmware blobs. Install:

```bash
emerge sys-kernel/linux-firmware
```

WiFi cards almost always need firmware. Check your specific chipset:
- Intel WiFi: `iwlwifi` firmware
- Broadcom: `b43` or `broadcom-sta`
- AMD GPU: `amdgpu` firmware in linux-firmware
- NVIDIA: proprietary driver bundles its own

---

## 8. Package Plan

List every package you want. For each, check USE flags at https://packages.gentoo.org.

### Template

```
# Window Manager / Desktop
x11-wm/dwm
x11-misc/dmenu
x11-terms/st
x11-misc/picom

# Shell
app-shells/fish

# Editor
app-editors/neovim

# Terminal tools
app-misc/tmux
sys-apps/ripgrep
sys-apps/fd

# Browser
www-client/firefox         # USE: -telemetry
# or
www-client/chromium        # USE: -hangouts

# Media
media-video/mpv
media-gfx/feh
media-gfx/imagemagick

# Audio
media-sound/pipewire

# Networking
net-misc/curl
net-misc/wget
net-misc/openssh

# Version Control
dev-vcs/git

# Fonts
media-fonts/noto
media-fonts/hack

# System
app-admin/sudo
sys-process/htop
```

### Per-package USE overrides

These go in `/etc/portage/package.use/` (one file per category or one big file):

```bash
# /etc/portage/package.use/browser
www-client/firefox -telemetry -wifi screencast

# /etc/portage/package.use/media
media-video/mpv vulkan lua vaapi

# /etc/portage/package.use/dev
dev-vcs/git -perl curl
```

---

## 9. Network Setup Plan

Decide your network management approach:

| Method | Complexity | Best for |
|--------|-----------|----------|
| `dhcpcd` + `wpa_supplicant` | Simple | Minimal setups, servers |
| NetworkManager | Medium | Laptops, mixed wired/wifi |
| `iwd` | Simple | Modern wifi-only replacement for wpa_supplicant |
| `netifrc` (Gentoo default) | Medium | OpenRC static configs |

For a suckless setup: `dhcpcd` for ethernet, `iwd` or `wpa_supplicant` for wifi.

---

## 10. Bootloader

| Bootloader | BIOS | UEFI | Notes |
|------------|------|------|-------|
| GRUB | Yes | Yes | Most documented, heaviest |
| efibootmgr | No | Yes | Direct UEFI boot, no bootloader needed |
| systemd-boot | No | Yes | Simple, systemd only |
| rEFInd | No | Yes | GUI picker, good for multi-boot |
| LILO | Yes | No | Legacy |

For UEFI: `efibootmgr` is the simplest. Just register the kernel directly with UEFI. No bootloader binary needed.

```bash
# Direct UEFI boot (no bootloader)
efibootmgr --create --disk /dev/sdX --part 1 \
  --label "Gentoo" --loader "\vmlinuz-6.x.x-gentoo" \
  --unicode "root=/dev/sdX3 ro"
```

---

## 11. Post-Install Checklist

```
[ ] Set timezone: ln -sf /usr/share/zoneinfo/Region/City /etc/localtime
[ ] Set locale: edit /etc/locale.gen, run locale-gen
[ ] Set hostname: /etc/hostname and /etc/hosts
[ ] Create user: useradd -m -G wheel,audio,video,usb -s /bin/fish username
[ ] Configure sudo: visudo (uncomment wheel group)
[ ] Enable services (OpenRC: rc-update add / systemd: systemctl enable)
[ ] Install and configure display server (Xorg)
[ ] Build and install suckless tools (dwm, st, dmenu)
[ ] Deploy dotfiles (stow srice)
[ ] Set up SSH keys
[ ] Configure firewall (iptables/nftables)
```

---

## 12. Compile Time Estimates

Gentoo compiles everything from source. Know what you're getting into:

| Package | Rough time (modern desktop) |
|---------|---------------------------|
| GCC | 30-60 min |
| LLVM/Clang | 30-60 min |
| Linux kernel | 10-30 min |
| Firefox | 60-120 min |
| Chromium | 120-240 min |
| LibreOffice | 60-120 min |
| Qt5/Qt6 | 30-60 min |
| Rust (bootstrapping) | 30-60 min |
| Xorg server | 5-10 min |
| dwm | <1 min |
| Most small packages | <5 min |

`MAKEOPTS="-jN"` where N = number of CPU threads. More threads = faster compile.

---

## 13. Useful References

- Gentoo Handbook (AMD64): https://wiki.gentoo.org/wiki/Handbook:AMD64
- USE flag index: https://www.gentoo.org/support/use-flags/
- Package search: https://packages.gentoo.org
- Kernel config guide: https://wiki.gentoo.org/wiki/Kernel/Configuration
- Gentoo Wiki (general): https://wiki.gentoo.org
- Portage manual: `man 5 make.conf`, `man 1 emerge`

---

## 14. Common Pitfalls

1. **Forgetting firmware**: WiFi/GPU won't work without `linux-firmware`
2. **Wrong kernel drivers**: If a driver is missing, the device is invisible. Use `lspci -k` to check what driver the live CD uses
3. **USE flag conflicts**: `emerge` will tell you. Read the messages, adjust flags
4. **Circular dependencies**: Occasionally happens. The wiki has workarounds for known ones
5. **Not reading elog messages**: `emerge` prints important post-install messages. Read them
6. **Skipping `dispatch-conf`**: After updates, config files need merging. Run `dispatch-conf` or `etc-update`
7. **World file management**: `emerge --depclean` removes orphaned packages. Run `emerge --depclean --pretend` first
8. **Sync before install**: Always `emerge --sync` before a big emerge session