Building qt-test¶

This guide provides comprehensive instructions for building the qt-test application from source.

Prerequisites¶

Required Software¶

All Platforms:

Qt Framework: Qt 6.9.3 or later
- Required modules: Quick, Bluetooth, Network, Location, Positioning
- Download from: https://www.qt.io/download
CMake: 3.16 or later
Git: For cloning the repository

Windows:

Visual Studio 2022 (Community, Professional, or Enterprise)
- Required workload: “Desktop development with C++”
- MSVC 2022 compiler (v143 or later)

Android:

Android NDK: r27 or later (installed via Qt Maintenance Tool or Android Studio)
Android SDK: API Level 21 (Android 5.0) minimum
Java Development Kit (JDK): OpenJDK 17 or later

Hardware Requirements¶

RAM: 8 GB minimum, 16 GB recommended
Disk Space: 10 GB free space (includes Qt, build artifacts)
For Android: USB debugging-enabled Android device or emulator

Quick Start¶

# Clone the repository
git clone <repository-url>
cd qt-test

# Open in Qt Creator
# File → Open File or Project... → Select CMakeLists.txt

# Configure with desired kit (Windows MSVC or Android)
# Build → Build (Ctrl+B)

Building for Windows (MSVC)¶

Open Project in Qt Creator¶

Launch Qt Creator
File → Open File or Project…
Navigate to qt-test directory
Select CMakeLists.txt

Configure Project¶

The Configure Project dialog appears:

Select Kit: Check Desktop Qt 6.9.3 MSVC2022 64bit
Build Configurations: Check both Debug and Release
Click Configure Project

Build¶

Select build configuration (Debug or Release) in the kit selector
Build → Build (Ctrl+B)
Build output appears in the Compile Output pane

Run¶

Build → Run (Ctrl+R)
Application launches with Qt Quick window

Build Artifacts:

Executable: build/Desktop_Qt_6_9_3_MSVC2022_64bit-Debug/qt-test.exe
Libraries are linked from: lib*/build/Desktop_Qt_6_9_3_MSVC2022_64bit-MinSizeRel/

Building for Android¶

Prerequisites¶

Ensure Android development tools are installed:

Open Qt Creator
Tools → Options → Devices → Android
Verify paths are configured:
- Android SDK Location: C:\Users\<user>\AppData\Local\Android\Sdk
- Android NDK: r27 or later
- JDK: OpenJDK 17 or later

Configure Android Kit¶

File → Open File or Project… → Select CMakeLists.txt
In Configure Project dialog:
- Check Android Qt 6.9.3 Clang arm64-v8a (64-bit ARM)
- Or Android Qt 6.9.3 Clang armeabi-v7a (32-bit ARM)
Build Configurations: Check Debug and Release
Click Configure Project

Connect Android Device¶

Enable USB Debugging on Device:

Open Settings → About Phone
Tap Build Number 7 times to enable Developer Options
Go to Settings → Developer Options
Enable USB Debugging
Connect device via USB

Verify Connection:

# Check device appears in adb
adb devices

# Should show:
# List of devices attached
# <device-id>    device

Build and Deploy¶

Select Android kit in Qt Creator
Build → Build (Ctrl+B)
Build → Deploy (deploys APK to device)
Build → Run (Ctrl+R) - Launches app on device

Build Artifacts:

APK: build/Android_Qt_6_9_3_Clang_arm64_v8a-Debug/android-build/build/outputs/apk/debug/android-build-debug.apk
Libraries are linked from: lib*/build/Android_Qt_6_9_3_Clang_arm64_v8a-MinSizeRel/

Library Configuration¶

Pre-built Libraries¶

This application uses three pre-built libraries for IP protection:

libNTRIPQt - NTRIP protocol parsing
libSQTPQt - SQTP transport protocol
libSQSPQt - SQSP message definitions

Default Configuration: MinSizeRel¶

Libraries are provided in MinSizeRel configuration (optimized for minimum binary size). The application can be built in any configuration (Debug, Release, etc.) but will always link to MinSizeRel libraries.

Library Locations:

Windows: lib*/build/Desktop_Qt_6_9_3_MSVC2022_64bit-MinSizeRel/
Android ARM64: lib*/build/Android_Qt_6_9_3_Clang_arm64_v8a-MinSizeRel/
Android ARMv7: lib*/build/Android_Qt_6_9_3_Clang_armeabi_v7a-MinSizeRel/

Switching Library Configuration (Advanced)¶

To test with different library configurations (Release vs MinSizeRel):

Open CMakeLists.txt
Find the Library Configuration Selection sections (lines ~115 and ~135)

Comment/uncomment the desired configuration:

# Release configuration
# set(LIB_BUILD_SUBDIR "Desktop_Qt_6_9_3_MSVC2022_64bit-Release")

# MinSizeRel configuration - ACTIVE
set(LIB_BUILD_SUBDIR "Desktop_Qt_6_9_3_MSVC2022_64bit-MinSizeRel")

IMPORTANT: Clear CMake cache (see Troubleshooting section)
Rebuild

Troubleshooting¶

Error: “missing and no known rule to make it”¶

Symptom:

ninja: error: 'C:/path/to/libNTRIPQt.lib', needed by 'qt-test.exe', missing and no known rule to make it

Cause: CMake cache contains old library paths after changing library configuration in CMakeLists.txt.

Solution: Clear CMake cache for all build configurations:

In Qt Creator:

Select each kit (Windows MSVC, Android ARM64, etc.)
For each kit:
- Build → Clear CMake Configuration
- Build → Run CMake (or build, which auto-runs CMake)
Build the project

Manual Deletion (Alternative):

# Delete all build directories
rm -rf build/Desktop_Qt_6_9_3_MSVC2022_64bit-Debug
rm -rf build/Android_Qt_6_9_3_Clang_arm64_v8a-Debug
# Repeat for all configurations

# Reopen project in Qt Creator to reconfigure

Why This Happens:

Each build configuration has its own CMake cache:

build/Desktop_Qt_6_9_3_MSVC2022_64bit-Debug/CMakeCache.txt
build/Android_Qt_6_9_3_Clang_arm64_v8a-Debug/CMakeCache.txt

When you change library paths in CMakeLists.txt, the cached library paths become stale. Qt Creator’s “Run CMake” doesn’t clear the cache - you must explicitly clear it.

Error: Android device not detected¶

Symptom: Qt Creator doesn’t show your Android device in the device list.

Solutions:

Check USB debugging: Settings → Developer Options → USB Debugging (enabled)
Verify ADB connection:
```
adb devices
```
Should show your device
Restart ADB server:
```
adb kill-server
adb start-server
```
Check USB cable: Try a different cable (some are charge-only)
USB connection mode: Set to “File Transfer” not “Charging only”

Error: Multiple OpenGL contexts (Android)¶

Symptom:

QRhiGles2: Failed to make context current
Failed to initialize graphics backend for OpenGL

Cause: Using multiple Window QML objects on Android (not supported).

Solution: This application uses a single ApplicationWindow with TabBar - no changes needed. If you’re modifying the UI, avoid creating additional Window objects.

Build Stuck or Slow¶

Solutions:

Clean build:
- Build → Clean All
- Build → Rebuild
Check disk space: Ensure 5+ GB free
Close other applications: Free up RAM
Disable antivirus scanning: Temporarily exclude build directory

Advanced Topics¶

Building for iOS (Future)¶

iOS support requires:

macOS with Xcode
Qt for iOS kit
Apple Developer account for device deployment

Library configuration in CMakeLists.txt includes iOS placeholders (not yet implemented).

Building for Linux (Future)¶

Linux support requires:

GCC 9+ or Clang 10+
Qt 6.9.3 for Linux
X11 or Wayland development libraries

Library configuration in CMakeLists.txt includes Linux placeholders (not yet implemented).

Custom Library Search Paths¶

To add custom library search paths, edit CMakeLists.txt:

find_library(LIBNTRIPQT_LIB
    NAMES NTRIPQt libNTRIPQt
    HINTS ${CMAKE_SOURCE_DIR}/libntripqt/build
          ${CMAKE_SOURCE_DIR}/../external/libs  # Add custom path
          /absolute/path/to/libs                # Absolute path
    PATH_SUFFIXES ${LIB_BUILD_SUBDIR}
    NO_CMAKE_FIND_ROOT_PATH
)

Multiple HINTS paths are searched in order until the library is found.

Integrating Your Own Libraries¶

If you need to add additional libraries:

Organize libraries using the same directory structure:

mylib/build/
├── Desktop_Qt_6_9_3_MSVC2022_64bit-Release/mylib.lib
└── Android_Qt_6_9_3_Clang_arm64_v8a-Release/libmylib.so

Add to CMakeLists.txt after existing libraries:

find_library(MYLIB_LIB
    NAMES mylib
    HINTS ${CMAKE_SOURCE_DIR}/mylib/build
    PATH_SUFFIXES ${LIB_BUILD_SUBDIR}
    NO_CMAKE_FIND_ROOT_PATH
)
if(MYLIB_LIB)
    list(APPEND FOUND_LIBS ${MYLIB_LIB})
endif()

Build configuration: You can use any configuration (Debug, Release, MinSizeRel, RelWithDebInfo) for your own libraries - the provided libraries use MinSizeRel, but this doesn’t restrict your libraries.
Clear CMake cache and rebuild.

Additional Resources¶

Full Documentation: See docs/_build_customer/index.html (HTML) or docs/_build_customer/latex/qt-test.pdf (PDF)
Qt Help: Import doxygen_output/docs/qt-test.qch into Qt Creator (Help → Documentation → Add…)
Qt Documentation: https://doc.qt.io/qt-6/
CMake Documentation: https://cmake.org/documentation/

Getting Help¶

For issues not covered in this guide:

Check Qt Creator’s Compile Output and Application Output panes
Review CMake configuration output
Consult the full documentation (HTML/PDF)
Check Qt documentation for platform-specific issues

Building qt-test¶

Prerequisites¶

Required Software¶

Hardware Requirements¶

Quick Start¶

Building for Windows (MSVC)¶

Open Project in Qt Creator¶

Configure Project¶

Build¶

Run¶

Building for Android¶

Prerequisites¶

Configure Android Kit¶

Connect Android Device¶

Build and Deploy¶

Library Configuration¶

Pre-built Libraries¶

Default Configuration: MinSizeRel¶

Switching Library Configuration (Advanced)¶

Troubleshooting¶

Error: “missing and no known rule to make it”¶

Error: Android device not detected¶

Error: Multiple OpenGL contexts (Android)¶

Build Stuck or Slow¶

Advanced Topics¶

Building for iOS (Future)¶

Building for Linux (Future)¶

Custom Library Search Paths¶

Integrating Your Own Libraries¶

Additional Resources¶

Getting Help¶

qt-test

Navigation

Related Topics