# Linux Platform Guide

This document provides Linux-specific information for MPV.Rocks Installer development and deployment.

## Table of Contents

- [Distributions](#distributions)
- [Package Managers](#package-managers)
- [Building](#building)
- [Installation](#installation)
- [Troubleshooting](#troubleshooting)

---

## Distributions

### Tested Distributions

**Ubuntu/Debian Family:**
- Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS
- Debian 11, 12
- Linux Mint 20, 21
- Pop!_OS 22.04

**Fedora/RHEL Family:**
- Fedora 38, 39
- RHEL 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9

**Arch Family:**
- Arch Linux
- Manjaro
- EndeavourOS
- Garuda Linux

**openSUSE Family:**
- openSUSE Tumbleweed
- openSUSE Leap

### Distribution Detection

**Automatic Detection:**
- Detected via `/etc/os-release`
- Provides distribution name and ID
- Used for package manager selection

**Supported Distros:**
- All major Debian-based distros
- All major Fedora-based distros
- Arch Linux and derivatives
- openSUSE and derivatives

---

## Package Managers

### APT (Debian/Ubuntu)

**Detection:**
```bash
which apt-cache
```

**Version Query:**
```bash
# Check installed version
apt-cache policy mpv | grep "Installed:"
```

**Installation:**
```bash
# Install from repository
sudo apt install mpv

# Install local package
sudo dpkg -i mpv-manager.deb
```

**Config Location:** `~/.config/mpv/`

### Flatpak

**Detection:**
```bash
which flatpak
```

**Version Query:**
```bash
# Check installed version
flatpak info io.mpv.Mpv | grep "Version:"
```

**Installation:**
```bash
# Install from Flathub
flatpak install flathub io.mpv.Mpv

# Install local file
flatpak install io.mpv.Mpv-installer.mpv
```

**Config Location:** `~/.var/app/io.mpv.Mpv/config/`

### Snap

**Detection:**
```bash
which snap
```

**Version Query:**
```bash
# Check installed version
snap list | grep mpv
```

**Installation:**
```bash
# Install from Snap Store
sudo snap install mpv

# Install local package
sudo snap install --dangerous ./mpv.snap
```

**Config Location:** `~/snap/mpv/current/`

### Homebrew

**Detection:**
```bash
# Intel/AMD (x86_64)
which brew
# Apple Silicon (arm64)
which brew
```

**Version Query:**
```bash
# Check installed version
brew list | grep mpv
```

**Installation:**
```bash
# Install from Homebrew
brew install mpv

# Install Cask (GUI apps)
brew install --cask mpv
```

---

## Building

### Build for Current Platform

```bash
# Build x86_64
make build-linux-x86_64

# Build static binary
CGO_ENABLED=0 make build-linux-x86_64
```

### Cross-Compilation

**From Linux to Windows:**
```bash
# Install MinGW-w64
sudo apt install mingw-w64

# Set cross-compilation environment
export CC=x86_64-w64-mingw32-gcc
export CXX=x86_64-w64-mingw32-g++
export GOOS=windows
export GOARCH=amd64

# Build
GOOS=windows GOARCH=amd64 go build -o dist/mpv-manager-win-x86_64.exe ./cmd/mpv-manager
```

**From Linux to macOS:**
```bash
# Install macOS cross-compiler
sudo apt install golang-1.20-go-darwin-arm64

# Build for Apple Silicon
GOOS=darwin GOARCH=arm64 CC=o64-clang go build -o dist/mpv-manager-darwin-arm64 ./cmd/mpv-manager
```

### Native Dependencies

**Linux build requirements:**
- GCC or Clang
- make
- libc development headers

**Optional for GPU detection:**
- mesa-utils (provides vainfo)
- mesa-dri-utils (provides glxinfo)
- vulkan-tools (provides vulkaninfo)

---

## Installation

### Portable Binary Installation

**Default Location:** `~/mpv/`

**Steps:**
```bash
# Extract binary
tar -xzf mpv-manager-linux-x86_64.tar.gz -C ~/

# Create symlink (optional)
ln -s ~/mpv/mpv-manager ~/bin/mpv-manager

# Run installer
~/mpv/mpv-manager
```

### System-Wide Installation

**To `/usr/local/bin`:**
```bash
# Extract to system directory
sudo tar -xzf mpv-manager-linux-x86_64.tar.gz -C /usr/local/

# Make executable
sudo chmod +x /usr/local/bin/mpv-manager
```

### Permissions

**Set executable permission:**
```bash
chmod +x mpv-manager
```

**Set proper ownership:**
```bash
sudo chown root:root /usr/local/bin/mpv-manager
sudo chgrp root /usr/local/bin/mpv-manager
```

---

## Troubleshooting

### Permission Denied

**Symptom:** "Permission denied" when accessing files or directories.

**Solution:**
```bash
# Run with sudo
sudo ./mpv-manager

# Fix directory permissions
sudo chown $USER:$USER ~/.config/mpv
```

### Missing Dependencies

**Symptom:** "Command not found" or "package not found".

**Solution:**
```bash
# Install missing dependency
sudo apt install <package-name>

# For missing build tools:
sudo apt install build-essential libc6-dev
```

### GPU Detection Issues

**Symptom:** GPU not detected or shows "unknown".

**Solutions:**

**1. Install GPU detection tools:**
```bash
sudo apt install mesa-utils mesa-dri-utils vulkan-tools
```

**2. Test detection manually:**
```bash
# Test vainfo
vainfo

# Test glxinfo
glxinfo -B | grep "Device"

# Test vulkaninfo
vulkaninfo --summary | grep deviceName
```

**3. Enable debug mode:**
```bash
./mpv-manager --debug
```

### Package Manager Issues

**APT Issues:**
```bash
# Update package cache
sudo apt update

# Fix broken packages
sudo apt --fix-broken install
sudo dpkg --configure -a
```

**Flatpak Issues:**
```bash
# Update Flatpak
flatpak update

# Check for Flatpak permission
flatpak permission-list
```

**Snap Issues:**
```bash
# Check snap status
snap list mpv

# Refresh snap
snap refresh
```

### Configuration Issues

**Config not saving:**
```bash
# Check config directory permissions
ls -la ~/.config/mpv/

# Check config file exists
test -f ~/.config/mpv/mpv.conf

# Check write permissions
test -w ~/.config/mpv/mpv.conf
```

**Config not loading:**
```bash
# Check config file syntax
cat ~/.config/mpv/mpv.conf

# Check for encoding issues
file ~/.config/mpv/mpv.conf
```

---

## Debugging

### Enable Debug Mode

```bash
./mpv-manager --debug
./mpv-manager --verbose
```

### Check Log File

**Log Location:** `~/.config/mpv/mpv-manager.log`

```bash
# View last 50 lines
tail -n 50 ~/.config/mpv/mpv-manager.log

# Follow log in real-time
tail -f ~/.config/mpv/mpv-manager.log
```

### Common Debug Commands

```bash
# Check version
./mpv-manager --version

# Check system info
./mpv-manager --debug 2>&1 | head -100

# Check platform detection
strace -e trace=open,openat ./mpv-manager
```

---

## Quick Reference

### Common Commands

```bash
# Build
make build-linux-x86_64

# Run
./mpv-manager-linux-x86_64

# Debug mode
./mpv-manager --debug

# Check version
./mpv-manager --version

# Test package manager
apt-cache policy mpv
flatpak info io.mpv.Mpv
snap list | grep mpv
```

### File Locations

| File | Location | Purpose |
|------|-----------|---------|
| Binary | `~/mpv/mpv-manager` | Main executable |
| Config | `~/.config/mpv/mpv.conf` | MPV configuration |
| Log | `~/.config/mpv/mpv-manager.log` | Application log |
| Backups | `~/.config/mpv/conf_backups/` | Config backups |

### Environment Variables

| Variable | Purpose | Example |
|----------|-----------|---------|
| `HOME` | User home directory | `/home/user` |
| `XDG_CONFIG_HOME` | Config directory | `/home/user/.config` |
| `PATH` | Binary search path | `/usr/local/bin:/home/user/bin` |
| `DISPLAY` | X11 display | `:0` |

---

## Conclusion

This Linux platform guide provides comprehensive information for building, installing, and troubleshooting MPV.Rocks Installer on Linux distributions.

For additional information, see:
- [Architecture](../ARCHITECTURE.md) - System architecture and design
- [Features](../FEATURES.md) - Comprehensive feature documentation
- [Troubleshooting](../TROUBLESHOOTING.md) - Common issues and solutions
- [Build & Deployment](../BUILD_DEPLOYMENT.md) - Build procedures and deployment guide