orbithub/docs/BUILDING.md

# Building OrbitHub (C++ / Qt6 Widgets)

Run all commands from the repository root unless noted.

## Requirements

Minimum toolchain requirements on all platforms:
- CMake 3.21+
- C++17 compiler toolchain
- Qt 6.2+ with `Widgets` and `Sql` modules (dynamic linking)
- OpenSSH client available on `PATH` (required for SSH sessions)

## Linux (Ubuntu / Mint)

```bash
sudo apt update
sudo apt install -y \
  build-essential cmake ninja-build git pkg-config \
  qt6-base-dev qt6-base-dev-tools qt6-tools-dev qt6-tools-dev-tools \
  openssh-client libssl-dev zlib1g-dev libjpeg-turbo8-dev

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/orbithub
```

## macOS (Homebrew)

```bash
xcode-select --install
brew update
brew install cmake ninja pkg-config qt@6 openssh openssl@3 jpeg-turbo

cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$(brew --prefix qt@6);$(brew --prefix openssl@3);$(brew --prefix jpeg-turbo)"
cmake --build build
open build/orbithub.app
```

## Windows 11 (PowerShell + MSVC + vcpkg)

Install required software:

```powershell
winget install -e --id Git.Git
winget install -e --id Kitware.CMake
winget install -e --id Ninja-build.Ninja
Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
  --override "--quiet --wait --norestart --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.Windows11SDK.22621"
```

Install dependencies via vcpkg:

```powershell
git clone https://github.com/microsoft/vcpkg C:\dev\vcpkg
C:\dev\vcpkg\bootstrap-vcpkg.bat
C:\dev\vcpkg\vcpkg.exe install qtbase:x64-windows openssl:x64-windows zlib:x64-windows libjpeg-turbo:x64-windows
```

Open `x64 Native Tools Command Prompt for VS 2022` (or Developer PowerShell), then build:

```powershell
cmake -S . -B build -G Ninja `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake `
  -DVCPKG_TARGET_TRIPLET=x64-windows
cmake --build build
```

Run (ensures DLL paths from vcpkg are present):

```powershell
C:\dev\vcpkg\vcpkg.exe env --triplet x64-windows -- .\build\orbithub.exe
```

If you already have `Qt 6` from the Qt installer and do not want vcpkg Qt, you can point CMake at that Qt install with `-DCMAKE_PREFIX_PATH=...`, but you still need compatible `OpenSSL`, `zlib`, and `libjpeg-turbo` development libraries (the first two for the embedded FreeRDP build; `libjpeg-turbo` for VNC's Tight encoding's JPEG sub-mode).

## Notes

- OrbitHub builds vendored `KodoTerm`, `libvterm`, and `FreeRDP` from `third_party/`.
- If Qt is installed in a custom location, pass `-DCMAKE_PREFIX_PATH=/path/to/Qt/6.x.x/<toolchain>` to CMake.
- Build output executable:
  - Linux: `build/orbithub`
  - macOS: `build/orbithub.app` (a proper app bundle, launch with `open build/orbithub.app`)
  - Windows: `build\\orbithub.exe`

## Linux Packaging

Build a Debian package (`.deb`) from the current Linux build:

```bash
./packaging/linux/build-deb.sh
```

Output path:
- `dist/orbithub_<version>_<arch>.deb`

Build a Flatpak bundle:

```bash
sudo apt-get install -y flatpak flatpak-builder
./packaging/flatpak/build-flatpak.sh
```

Output path:
- `dist/flatpak/org.darksingularity.OrbitHub.flatpak`

## Windows Packaging

Requires [Inno Setup 6](https://jrsoftware.org/isinfo.php) (`winget install -e --id JRSoftware.InnoSetup`).

From a configured and built `build\` directory (see Windows build steps above):

```powershell
.\packaging\windows\build-installer.ps1
```

Output path:
- `dist\windows\OrbitHub-Setup-<version>.exe`

## macOS Packaging

Requires `qt@6` from Homebrew (for `macdeployqt`). For a custom volume icon on
the `.dmg`, also install `SetFile` (via Xcode's "Additional Tools", from
[developer.apple.com/download/all](https://developer.apple.com/download/all))
or `brew install fileicon` — packaging still works without either, just with
the generic disk image icon.

```bash
./packaging/macos/build-dmg.sh
```

This runs `cmake --install`, then `macdeployqt` to bundle Qt frameworks and
plugins into the `.app`, then re-signs the bundle (ad hoc, since there is no
Developer ID certificate) so it passes macOS's launch-time code-integrity
check. The result is unsigned/unnotarized, so first launch requires
right-click → **Open** to bypass Gatekeeper's unidentified-developer warning.

Output path:
- `dist/macos/OrbitHub-<version>.dmg`

## User Guide PDF

The in-app User Guide (`Help -> User Guide`) is built from
`docs/USER_GUIDE.md` and embedded into the app at compile time — no extra
step needed for that. A standalone PDF version is generated separately by a
small tool (kept out of the main app's dependencies, since it needs
`Qt6::PrintSupport`):

```bash
./packaging/docs/build-user-guide-pdf.sh
```

Output path:
- `docs/USER_GUIDE.pdf` (not committed to git — a release asset, like the
  platform installers)