Internal
Public Access
ksmithandClaude Sonnet 5
ce1e40a12d
Adds docs/USER_GUIDE.md, a 10-section end-user guide (getting started, managing/organizing profiles, SSH and RDP connections, session management, settings, troubleshooting). It's embedded into the app binary via a Qt resource file and rendered by a new Help -> User Guide window: a topic sidebar plus content pane, not a single scrolling document, with cross-reference links between sections routed to sidebar selection rather than relying on Qt's Markdown importer's lack of heading anchors. A separate, non-shipped tool (tools/user-guide-pdf/) renders the same source to a standalone PDF via QTextDocument + QPrinter, wrapped by packaging/docs/build-user-guide-pdf.sh. Kept fully outside the main CMake target so Qt6::PrintSupport never becomes a runtime dependency of the shipped app (confirmed via ldd). The PDF itself isn't committed -- generated per release like the platform installers. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
159 lines
4.7 KiB
Markdown
159 lines
4.7 KiB
Markdown
# 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
|
|
|
|
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
|
|
|
|
cmake -S . -B build -G Ninja \
|
|
-DCMAKE_BUILD_TYPE=Release \
|
|
-DCMAKE_PREFIX_PATH="$(brew --prefix qt@6);$(brew --prefix openssl@3)"
|
|
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
|
|
```
|
|
|
|
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` and `zlib` development libraries for the embedded FreeRDP build.
|
|
|
|
## 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)
|