Build from Source

Build OctoMY™ from source code using Qt and the Qbs build system.

Pro Tip

Use Qt's online installer for the cleanest setup - it includes Qbs and all optional Qt modules. Package manager versions often lag behind and may be missing modules like Bluetooth or Positioning.

Prerequisites

Required software

Linux dependencies

Debian/Ubuntu:

# Install Qt 6 and tools
sudo apt install qt6-base-dev qt6-multimedia-dev qt6-serialport-dev
sudo apt install qt6-positioning-dev qt6-svg-dev qt6-sensors-dev
sudo apt install libqt6opengl6-dev qt6-tools-dev qt6-shadertools-dev

# Install build tools + linker (mold is required for the default debug build)
sudo apt install build-essential git cmake mold

# Mandatory system libraries (the link step needs these -dev packages).
# The apt Qt -dev packages pull most of them in transitively, but install
# them explicitly when building against a Qt-installer ~/Qt:
sudo apt install libudev-dev libgl1-mesa-dev libglu1-mesa-dev libvulkan-dev

# Install Qbs (if not included with Qt)
sudo apt install qbs

# Optional: lld is only needed for release builds (config:release + LTO)
sudo apt install lld

For the full mandatory-vs-optional breakdown (and the gotcha where a Qt-installer ~/Qt does not provide the system -dev libraries), see Build for Linux desktop → Prerequisites.

Fedora:

# Install Qt 6
sudo dnf install qt6-qtbase-devel qt6-qtmultimedia-devel
sudo dnf install qt6-qtserialport-devel qt6-qtpositioning-devel
sudo dnf install qt6-qtsvg-devel qt6-qtsensors-devel

# Build tools
sudo dnf install gcc-c++ git cmake qbs

Arch Linux:

sudo pacman -S qt6-base qt6-multimedia qt6-serialport qt6-positioning
sudo pacman -S qt6-svg qt6-sensors qt6-tools
sudo pacman -S base-devel git cmake qbs

Qt installation via Qt Installer

For the latest Qt with all modules:

1. Download Qt Online Installer
2. Run and select:
   • Qt 6.x for Desktop
   • Qt Creator
   • Qt Debug Information Files (optional)

Step 1: Clone the repository

# Clone with submodules
git clone --recursive https://github.com/mrdeveloperdude/OctoMY.git
cd OctoMY

# If already cloned without --recursive
git submodule update --init --recursive

Step 2: Configure Qbs

First-time setup

# Configure Qbs to use your Qt installation
qbs setup-toolchains --detect

# Setup Qt profile
qbs setup-qt /path/to/qmake qt6

# List available profiles
qbs config --list profiles

Profile configuration

For Qt installed via package manager:

qbs setup-qt /usr/bin/qmake6 qt6

For Qt installed via Qt Installer:

qbs setup-qt ~/Qt/6.8.3/gcc_64/bin/qmake qt6

Verify configuration

qbs config profiles.qt6.baseProfile
# Should show: gcc or clang

Step 3: Build the project

Resolve (first time and after file changes)

The build system uses cached file discovery — source files are scanned once during qbs resolve and cached across subsequent builds. This reduces incremental build overhead from ~2 minutes to ~3 seconds.

# First resolve (scans all source directories, runs probes)
qbs resolve

# Force re-scan (e.g. after checking out a different branch)
qbs resolve --force-probe-execution

When to re-run qbs resolve:

• After adding or removing .cpp, .hpp, .ui, or resource files
• After running qbs run -p analyze-deps (cross-library includes changed)
• After checking out a branch with different files
• After enabling/disabling features in oc_use.json

Build

# Build main applications
qbs build --products hub,agent,remote

# Build everything (all libs, apps, tests)
qbs build

Debug vs Release

qbs build config:debug      # Default: -g -O0
qbs build config:release    # Optimized: -O2

File cache modes

The project.fileCacheMode property controls source file discovery:

# Bypass cache for one build
qbs build project.fileCacheMode:"never"

Dependency manifest

Cross-library #include paths are managed by integration/qbs/dep_manifest.json. When you add an #include that references a header from another library, update the manifest:

qbs run -p analyze-deps
qbs resolve --force-probe-execution

Optional features (oc_use.json)

Create oc_use.json in the project root (gitignored) to disable expensive features per workstation:

{
  "llvm": false,
  "webEngine": false,
  "multimedia": false,
  "fem": false
}

Available keys: bluetooth, positioning, sensors, serialPort, webSockets, webEngine, pdf, multimedia, llvm, fem, llama, kwin, rl.

Step 4: Build output

Build artifacts are placed in:

default/
├── install-root/
│   └── usr/local/bin/
│       ├── agent       # Agent executable
│       ├── remote      # Remote executable
│       ├── hub         # Hub executable
│       └── zoo         # Zoo executable
└── <product-name>/
    └── <config>/
        └── <executable>

Run built applications

# Run Agent
./default/install-root/usr/local/bin/agent --personality Test

# Run Remote
./default/install-root/usr/local/bin/remote --personality Test

# Run with debug output
./default/install-root/usr/local/bin/agent --debug

Build specific targets

List available products

qbs list-products -f project.qbs

Build single target

# Build only the Agent
qbs build -f project.qbs profile:qt6 -p agent

# Build only tests
qbs build -f project.qbs profile:qt6 -p "test*"

Build with kiln

Kiln builds the tree without qbs, without a compiler or linker on the machine, and without the git command: it carries clang, lld and the part of git it needs. What it still needs is the operating system, a Qt installation, a network path to the source, and on Windows the Build Tools and the Windows SDK.

No release ships kiln yet, so build it once with qbs:

qbs build -p kiln config:release

Then one command fetches a commit, provisions the pinned source trees the build uses (LLVM, the validation layer and the rest), and builds and installs every program the install tree holds:

kiln bootstrap https://gitlab.com/octomy/octomy.git main ~/octomy-kiln \
    --qmake ~/Qt/6.11.1/gcc_64/bin/qmake6

main can be a branch, a tag or a commit. The programs land in ~/octomy-kiln/release/install-root/usr/local/bin. The command writes the Qt it was given into ~/octomy-kiln/.kiln.local, the file for this machine's settings, so later commands in that folder need no flag:

cd ~/octomy-kiln
kiln test --variant release          # every suite, each held to its contract
kiln build src/construct             # one program, in debug
kiln package deb                     # the Debian package, as the release builds it

Every compile and link goes through the kiln broker, which keeps the machine usable while it builds. kiln status says what runs and what waits; the kiln reference lists every command and key.

Cross-Compilation

Android build

# Setup Android NDK profile
qbs setup-android --ndk-dir ~/Android/Sdk/ndk/25.1.8937393 android

# Build for Android
qbs build -f project.qbs profile:android

Raspberry Pi (ARM)

# Setup ARM toolchain
qbs setup-toolchains --detect

# Build for ARM
qbs build -f project.qbs profile:arm-linux

Build options

Project properties

Example

qbs build project.wantWebEngine:false project.wantLlvm:false

Branding

The default build carries the OctoMY edition — names, palette seed colors, logo — compiled in at resolve time from integration/editions/octomy/. To brand a build as something else, point project.editionDir at your own edition directory; see Build a branded edition.

Clean build

# Clean build artifacts
qbs clean -f project.qbs

# Full clean (removes build directory)
rm -rf default/

# Clean and rebuild
qbs clean && qbs build -f project.qbs profile:qt6

IDE integration

Qt Creator

1. Open project.qbs in Qt Creator
2. Configure kit (Qt 6 + Qbs)
3. Build and run from IDE

Visual Studio Code

Install extensions:

• C/C++ (Microsoft)
• Qbs Tools

Configure settings.json:

{
    "qbs.qbsPath": "/usr/bin/qbs",
    "qbs.settingsDirectory": "~/.config/QtProject/qbs"
}

Troubleshooting

"Qt not found"

# Verify Qt installation
qmake6 --version

# Check Qbs profile
qbs config profiles.qt6

# Reconfigure
qbs setup-qt $(which qmake6) qt6

"Module not found"

# Install missing Qt module
sudo apt install qt6-<module>-dev

# Example for Bluetooth
sudo apt install qt6-connectivity-dev

Compiler errors

# Check compiler version (need C++20)
g++ --version

# Should be GCC 10+ or Clang 11+

"qbs: command not found"

# Install Qbs
sudo apt install qbs

# Or use Qt's Qbs
export PATH=~/Qt/Tools/QtCreator/bin:$PATH

Build fails with OpenGL

# Install OpenGL development files
sudo apt install libgl1-mesa-dev libglu1-mesa-dev

Dependencies reference

Core Qt modules

Optional Qt modules

Third-party libraries

OctoMY™ includes these as submodules:

• mbedTLS (cryptography)
• QMapControl (maps)
• QHexEdit (binary editor)
• Hoedown (Markdown)