building

Building QElectroTech

Instructions for building QElectroTech from source code.

Prerequisites

Before building, ensure you have the right tools and libraries installed.

Qt6 is the default. As of a1c090781 (September 2026) CMakeLists.txt sets QT_VERSION_MAJOR to 6 when nothing is specified, and the Qt5 track has been retired. Qt 5.15 reached end of life in 2025. Build with Qt5 only if you have a specific reason, by passing -DQT_VERSION_MAJOR=5.

Linux

Ubuntu/Debian:

sudo apt update
sudo apt install build-essential cmake ninja-build git pkg-config

# Qt6
sudo apt install qt6-base-dev qt6-base-private-dev libqt6svg6-dev \
                 libqt6sql6-sqlite qt6-tools-dev qt6-tools-dev-tools \
                 qt6-l10n-tools libqt6pdf6 qt6-pdf-dev

# SQLite, and CUPS -- see the note below on why CUPS is needed
sudo apt install libsqlite3-dev libcups2-dev

On Ubuntu 22.04 you may also need libgl1-mesa-dev and libegl1-mesa-dev.

Fedora/RHEL:

sudo dnf groupinstall "Development Tools"
sudo dnf install cmake ninja-build git qt6-qtbase-devel qt6-qtsvg-devel \
                 qt6-qttools-devel sqlite-devel cups-devel

Arch Linux:

sudo pacman -S base-devel cmake ninja git qt6-base qt6-svg qt6-tools \
               sqlite libcups

Why CUPS is required

QElectroTech itself does not use CUPS. By default the build also compiles two KDE Frameworks libraries (KF6CoreAddons, KF6WidgetsAddons) from source, and those require CUPS for print-dialog support. Without the development headers, configuring fails before anything is compiled:

-- Could NOT find Cups (missing: CUPS_LIBRARIES CUPS_INCLUDE_DIR)
CMake Error at .../FeatureSummary.cmake:869 (message):
  feature_summary() Error: REQUIRED package(s) are missing, aborting CMake

Two ways out: install the CUPS development package as above, or install the KDE Frameworks packages your distribution provides and configure with -DBUILD_KF=NO so the build uses those instead of compiling its own.

macOS

1. Install Xcode Command Line Tools:

   xcode-select --install

2. Install dependencies via Homebrew:

   brew install cmake ninja git qt

   Homebrew's qt formula is Qt6. qt@5 is only needed for a deliberate Qt5 build.

3. Set Qt path (if needed):

   export Qt6_DIR=$(brew --prefix qt)/lib/cmake/Qt6

Windows

Option 1: Visual Studio (Recommended)

1. Install Visual Studio Community (free)
   • Select "Desktop development with C++"
   • Includes MSVC compiler
2. Install CMake from cmake.org
3. Install Qt6 from qt.io
   • Choose "MSVC 2019 64-bit" (or 2022)

Option 2: MinGW (Alternative)

1. Install MinGW with C++ support
2. Install CMake
3. Install Qt6 (MinGW build)

Option 3: WSL (Windows Subsystem for Linux)

1. Enable WSL2
2. Install Ubuntu in WSL
3. Follow Linux instructions above

Git & Source Code

Clone the repository with submodules:

git clone --recursive https://github.com/qelectrotech/qelectrotech-source-mirror.git
cd qelectrotech-source-mirror

The --recursive flag is important to get all dependencies.

---

Building from Source

Step 1: Clone the Repository

git clone https://github.com/qelectrotech/qelectrotech-source-mirror.git
cd qelectrotech-source-mirror

Step 2: Configure the Build

mkdir build && cd build
cmake ..

Step 3: Compile

cmake --build . --config Release

Or use your platform's build tool:

Linux/macOS:

make -j$(nproc)

Windows (MSVC):

cmake --build . --config Release --parallel

Step 4: Install (Optional)

cmake --install .

Or run the binary from the build directory.

---

Building Variants

Debug Build

cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build .

With AddressSanitizer (ASAN)

cmake -DCMAKE_CXX_FLAGS="-fsanitize=address" ..
cmake --build .

With ThreadSanitizer (TSan)

cmake -DCMAKE_CXX_FLAGS="-fsanitize=thread" ..
cmake --build .

With 3D mouse support

Off by default. Turn it on with -DQET_ENABLE_SPACEMOUSE=ON; it needs libspnav or hidapi, and builds without the feature (with a warning) if neither is found:

cmake -DQET_ENABLE_SPACEMOUSE=ON -DQET_SPACEMOUSE_BACKEND=hid ..

Backends, packages and what each needs at run time: 3D mouse, §7.

---

Troubleshooting Build Issues

Could NOT find Cups

-- Could NOT find Cups (missing: CUPS_LIBRARIES CUPS_INCLUDE_DIR)
CMake Error at .../FeatureSummary.cmake:869 (message):
  feature_summary() Error: REQUIRED package(s) are missing, aborting CMake

The build compiles two KDE Frameworks libraries from source by default, and they need CUPS. Install the development package (libcups2-dev, cups-devel, or libcups depending on distribution), or configure with -DBUILD_KF=NO to use your distribution's KDE Frameworks packages instead.

The following REQUIRED packages have not been found: Qt6

Usually a stale dependency cache rather than a missing package — most often seen after the Qt6 default landed, on a tree that had previously been configured for Qt5.

The fetched dependencies are cached outside the build directory, in ~/.cache/qet-deps. Deleting the build directory alone does not clear it, so the cached Extra CMake Modules stay configured for the old Qt version and fail demanding the new one. Remove the cache and configure again:

rm -rf ~/.cache/qet-deps build/
cmake -S . -B build -G Ninja

CMake can't find Qt

Point CMake at the Qt installation explicitly:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/Qt/6.x.x/gcc_64

On macOS with Homebrew, export Qt6_DIR=$(brew --prefix qt)/lib/cmake/Qt6.

Mixing Qt versions

INTERFACE_QT_MAJOR_VERSION of "Qt5::Core" does not agree with QT_MAJOR_VERSION means parts of the build found Qt5 and parts found Qt6. Configure from a clean build directory and pass -DQT_VERSION_MAJOR so the choice is explicit rather than inferred.

---

Building in Docker

See the project's Dockerfile for containerized builds:

docker build -t qelectrotech:release .
docker run -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix qelectrotech:release

---

Build Optimization

Faster Builds

Tips for speeding up compilation

Parallel Builds

Using multiple cores for faster compilation

Incremental Builds

Only rebuilding changed files

---

Running Tests

After building, run the test suite:

ctest

Or:

make test

---

Contributing Changes

See Contributing for guidelines on submitting code changes.

---

Getting Help

• Forum — Build problems discussion
• Issues — Report build-related bugs
• Developer Docs — Architecture reference