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)

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)

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:

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:

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:

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):

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:

./packaging/linux/build-deb.sh

Output path:

• dist/orbithub_<version>_<arch>.deb

Build a Flatpak bundle:

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 (winget install -e --id JRSoftware.InnoSetup).

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

.\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) or brew install fileicon — packaging still works without either, just with the generic disk image icon.

./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):

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

Output path:

• docs/USER_GUIDE.pdf (not committed to git — a release asset, like the platform installers)