# Installation

## Requirements
- macOS 14+
- Xcode 15+ (for GUI runs) or Swift toolchain 5.9+ (for CLI builds)

## Dependencies (via Homebrew)
One command covers everything optional:

```bash
brew install sshpass freerdp
```

| Tool | Purpose | Required? | Install |
|------|---------|-----------|---------|
| Xcode Command Line Tools | building (`swift build`, C helper) | build only | `xcode-select --install` |
| `sshpass` | password auto-login from Keychain (no typing) | optional | `brew install sshpass` |
| `xfreerdp` (FreeRDP) | native RDP sessions | optional | `brew install freerdp` |
| `ssh`, `sftp`, `ssh-keyscan`, `ssh-keygen` | SSH core, host-key fingerprints | built into macOS | — |
| SwiftTerm | terminal emulator | bundled via SPM | — |
| Microsoft Remote Desktop | RDP fallback without FreeRDP | optional | App Store |

Without `sshpass`: passwords are asked interactively in the terminal tab.
Without FreeRDP: RDP profiles open Microsoft Remote Desktop instead.

## Option A: Xcode (recommended for GUI)
1. `open Package.swift` in `RemminaMac/`
2. Select target `RemminaMac`, destination `My Mac`
3. `Cmd+R` → app launches
4. First launch creates:
   - `~/Library/Application Support/RemminaMac/profiles.json`
   - `~/Library/Application Support/RemminaMac/sshkeys.json`

## Option B: Swift CLI
```bash
cd RemminaMac
swift build
.build/debug/RemminaMac
```

## Option C: Release binary (no Xcode)
```bash
./scripts/build-release.sh
unzip dist/RemminaMac-*-macos-arm64.zip -d /tmp/rmm
/tmp/rmm/RemminaMac
```

## Option D: Installer DMG (recommended for end users)
1. Download `RemminaMac-<version>-macos-arm64.dmg` from a Gitea release
   (or build locally: `./scripts/build-app.sh <version> && ./scripts/build-dmg.sh <version>`)
2. Double-click the DMG → Finder window with `RemminaMac.app` + `Applications` link
3. Drag `RemminaMac.app` onto `Applications` → `/Applications/RemminaMac.app`
4. Eject, launch from Applications. First launch: right-click → Open
   (ad-hoc signature, no Apple notarization).
```bash
# Verify:
spctl -a -vv dist/RemminaMac.app
hdiutil verify dist/RemminaMac-*-macos-arm64.dmg
```

## RDP requirements
```bash
# For full RDP support (see dependency table above):
brew install freerdp
which xfreerdp
# Without FreeRDP: install Microsoft Remote Desktop from the App Store
```

## SSH auto-login (optional)
```bash
brew install sshpass
# Enables password auto-login from Keychain (no typing).
# Without sshpass: the password prompt appears inside the terminal tab.
# Full list: dependencies table in [docs/INSTALL.md](docs/INSTALL.md#dependencies-via-homebrew).
```

## Troubleshooting
- `swift build` fails → check `swift --version` (>= 5.9), Xcode Command Line Tools: `xcode-select --install`
- Keychain prompt → allow once, service `RemminaMac`
- `xfreerdp` not found → fallback uses `rdc://`, needs MS Remote Desktop