Files
qt-migration-legatus/qt6-after/qt6-migrated-legatus
berrux-dev b18ac87565 Document the Release 2 driver in the README and tidy DDS/Plugins
- Rewrite README.md around new_docker_build_release2.sh: Release 2
  scope (4 build groups, 61 targets), Ninja/RelWithDebInfo configure,
  the 22-test ctest baseline, DEB production via
  rpmbuild/make_rpm_ubuntu26_release2.py, options reference,
  troubleshooting and known quirks (the legacy validation-scope driver
  is no longer documented as the main flow).
- Remove leftover blank lines and stale explanatory comments in
  Lts/DDS/Generic (dynamic_data_reader.h, generic_base.h),
  Lts/DDS/QosProfile (DDS_DefaultQos.cpp/.h, CMakeLists.txt) and
  Lts/Plugins/CMakeLists.txt.
2026-11-17 20:14:47 +01:00
..
2026-10-15 20:43:46 +02:00
2026-08-13 16:59:32 +00:00
2026-10-13 22:20:11 +02:00

qt6-migrated-legatus — build and run, step by step

Build guide for the Qt6-migrated legatus tree on the Release 2 branch. Everything runs inside a prebuilt Docker image; the host only needs Docker.

Scope

new_docker_build_release2.sh builds the Release 2 scope in four groups (all ON by default, toggle with --groupN / --no-groupN):

Group Area Contents
GROUP1 (AP4) DDS middleware ddscore, ddsftccore, ddsfts, ddsgen, ddsQoS, ddsconnector (+ ddscore_unit_test, ddsqos_unit_test)
GROUP3 (AP3) Lts services + core stack NGL library stack (NGLLogger, nglcoreapplication, nglcompression, …), Lts/Common libraries (LtsCoordinate, LtsCoordTrans, LtsSession, LtsLicence, …), TetraIF modules (CoPrtCnv, LogView, PrtCnv) and all their test executables
GROUP5 (AP9) Viewer / tools ddsview, LogViewer, sqlbrowser (+ logviewer_unit_test, sqlbrowser_unit_test)
GROUP6 (AP9) Generators ngl_codegen

61 targets in total, built one by one (cmake --build ../build --target <t> -j$(nproc)).

Entries at the tree root:

  • new_docker_build_release2.sh — build driver (compile, ctest, DEB packaging)
  • rpmbuild/make_rpm_ubuntu26_release2.py — in-tree DEB package producer (self-contained)
  • Dockerfile — image recipe kept for the legacy validation-scope driver and for the qt6-release-build-pipeline DEB; the Release 2 driver carries the same recipe built in and builds the image automatically when it is missing
  • rti_license.dat — RTI Connext DDS license, required by the DDS group (GROUP1)
  • jenkins-ci-rme/ — in-tree copy of the Jenkins CI flow (see its own README.md; still wired to the legacy driver, see Step 5)
  • ../build/ — build tree, created by the driver next to the tree (qt6-after/build), never inside it (git-ignored scratch area)

Toolchain inside the image: Ubuntu 26.04, GCC 15.2.0, Qt 6.10.2 (/opt/Qt/6.10.2/gcc_64), C++17 (set by the root CMakeLists.txt), Ninja, RelWithDebInfo. The DDS group requires rti_license.dat (checked in at the tree root); the driver exports RTI_LICENSE inside the container.

Prerequisites

  1. Docker available on the host.
  2. A .envrc in this directory defining MIGRATE_PIPELINE_ROOT — the pipeline root, i.e. the directory that contains qt-migration-legatus/. The driver mounts it at /repo in the container (overridable with --docker-mount-root) and works in /repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus, so running the driver as-is satisfies this. The build tree then lives at /repo/qt-migration-legatus/qt6-after/build in the container, which is ../build next to the tree on the host.

MIGRATE_PIPELINE_ROOT resolution (highest precedence first): exported environment variable → .envrc in this directory → the script's own location.

The driver refuses to start if .envrc is missing, if MIGRATE_PIPELINE_ROOT is unset or the directory does not exist, or if rti_license.dat is missing while GROUP1 is ON.

All commands below are run from this directory (qt6-migrated-legatus/).

Step 1 — Build the prebuilt Docker image (once)

./new_docker_build_release2.sh --docker-image legatus-qt6:1.0

--docker-image selects the prebuilt-image mode: if the named image does not exist yet, the driver builds it automatically from its built-in recipe (Ubuntu 26.04 base, apt deps, Qt 6.10.2 via aqtinstall, KDReports from source) and continues with the build. The default image name is qt6-migrated-legatus-release2. This driver has no --build-prebuilt-image / --delete-prebuilt-image options — manage the image with plain docker if needed.

Step 2 — Build the Release 2 scope

./new_docker_build_release2.sh --docker-image legatus-qt6:1.0 \
  > build.log 2>&1

What the driver does:

  1. Validates the environment (.envrc, MIGRATE_PIPELINE_ROOT, rti_license.dat for GROUP1) and starts a container with -v ${MIGRATE_PIPELINE_ROOT}:/repo and working directory /repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus.

  2. Inside the container, it wipes and reconfigures the build tree next to the source tree:

    rm -rf ../build && mkdir -p ../build
    cmake -B ../build -G Ninja \
      -DBUILD_TESTING=ON \
      -DCMAKE_BUILD_TYPE=RelWithDebInfo \
      -DCMAKE_PREFIX_PATH=/opt/Qt/6.10.2/gcc_64 \
      -DCMAKE_CXX_FLAGS="-DRTI_LINUX -DRTI_UNIX" \
      -DCMAKE_C_FLAGS="-DRTI_LINUX -DRTI_UNIX" \
      -DBUILD_RTI=ON \
      -DBUILD_GROUP1=ON -DBUILD_GROUP3=ON -DBUILD_GROUP5=ON -DBUILD_GROUP6=ON \
      # + packaging/coverage pass-through variables (see Troubleshooting)
    
  3. Builds the 61 group targets in order (GROUP1 → GROUP3 → GROUP5 → GROUP6).

  4. Runs ctest (see Step 3).

Output to inspect after the run:

  • ../build/bin/ — executables (apps: ddsview, LogView, LogViewer, PrtCnv, sqlbrowser, ngl_codegen, …)
  • ../build/bin/unit-test/ — the 22 test executables
  • ../build/lib/ — shared libraries

To rebuild incrementally without a fresh tree, run the build directly in an interactive container against the existing ../build/:

docker run --rm -it -v /path/to/pipeline-root:/repo legatus-qt6:1.0 \
  bash -c 'cd /repo/qt-migration-legatus/qt6-after/build \
  && cmake --build . -j$(nproc)'

Run an executable directly

To run a built executable interactively — e.g. the GUI apps under ../build/bin/ (ddsview, LogViewer, sqlbrowser) against your local display — start a shell inside the container with X11 forwarding:

docker run --rm -it \
  -e DISPLAY \
  -e LC_ALL=C.UTF-8 \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v /path/to/pipeline-root:/repo \
  legatus-qt6:1.0 \
  bash -c 'cd /repo/qt-migration-legatus/qt6-after/build && exec bash'

Step 3 — Run the tests

3.1 ctest (automatic)

The driver runs ctest after the compile (skip with --no-ctest): it cds into ../build, sets QT_QPA_PLATFORM=offscreen and prepends the system Qt plugin dir to QT_PLUGIN_PATH (/usr/lib/x86_64-linux-gnu/qt6/plugins — where the system libkf6texttemplate-dev package installs ktexttemplate_defaulttags, needed by GrantleeParserSmoke; the /opt/Qt install does not search it), then runs ctest --output-on-failure -j$(nproc).

A failing test does not fail the driver run (it logs and continues).

Expected baseline — 22 tests, all passed:

# Test Area
1 coprtcnv_unit_test TetraIF/CoPrtCnv — telegrams, fragmentation
2 logview_unit_test TetraIF/LogView — IntegerCalculator
3 prtcnv_unit_test TetraIF/PrtCnv — fragmented-telegram handling
4 wms_json_ds_unit_test Z/wms_json_ds
5 nglcoreapplication_unit_test Z/nglcoreapplication
6 nglsettings_unit_test Z/nglsettings
7 NGLToolsQtSmoke Z/ngltools — Qt smoke (binary ngltools_qt_smoke)
8 ngltools_unit_test Z/ngltools
9 test_nglpdfwidget Z/nglwidgets — PDF widget
10 ngllogger_unit_test Z/NGLLogger
11 logviewer_unit_test Lts/LogViewer
12 sqlbrowser_unit_test Lts/SQLBrowser
13 ddsqos_unit_test Lts/DDS/QosProfile
14 ddscore_unit_test Lts/DDS core
15 GrantleeParserSmoke Lts/Common/CodeGen — KTextTemplate parsing (binary grantlee_parser_smoke)
16 codegen_unit_test Lts/Common/CodeGen
17 commandlineparser_unit_test Lts/Common — command-line parser
18 lts_coord_trans_unit_test Lts/Common/LtsCoordTrans
19 ltscoordinate_unit_test Lts/Common/LtsCoordinate
20 aes_crypt_test Lts/Common/LtsLicence — AES
21 ltssession_unit_test Lts/LtsSession
22 utils_test Lts/Common/LtsUtils

3.2 Run a test executable directly

GUI-free tests need the offscreen Qt platform in a headless container:

docker run --rm -it -v /path/to/pipeline-root:/repo legatus-qt6:1.0 \
  bash -c 'export QT_QPA_PLATFORM=offscreen
export QT_PLUGIN_PATH=/usr/lib/x86_64-linux-gnu/qt6/plugins
cd /repo/qt-migration-legatus/qt6-after/build
./bin/unit-test/utils_test        # LtsUtils: byte access, strings, …
./bin/unit-test/coprtcnv_unit_test
# or everything registered:
ctest --output-on-failure'

Each QtTest binary accepts a single slot name to run just one test, e.g. ./bin/unit-test/utils_test byteAccess.

Note: ctest reads the absolute paths embedded in the build tree at configure time — run it against ../build with the same mount prefix the configure used (the driver mounts the pipeline root at /repo).

Step 4 — Produce the release DEB packages

./new_docker_build_release2.sh --docker-image legatus-qt6:1.0 \
  --run-jenkins-builder \
  > /path/to/build.log 2>&1

(Export PROJECT, LTS_VERSION, BUILD_NUMBER, BUILD_TAG, GUEZ_MODE before the command if you want non-default package metadata — command-prefix variables are not expanded in the same command's arguments.)

The driver compiles the scope, runs ctest, then stages the tree (tar) into <pipeline-root>/deb_stage/ and runs the in-tree rpmbuild/make_rpm_ubuntu26_release2.py (-c LTS, IPO + unity build, BUILD_RTI=ON, all 61 targets), which produces 5 DEBs in <pipeline-root>/rpms/<project>/<os-version>/:

DEB Contents
qt6-release-runtime_* runtime libraries + the release-scope executables
qt6-release-sources_* release-scope sources
qt6-release-ctest-runtime_* test executables
qt6-release-ctest-sources_* test sources
qt6-release-build-pipeline_* the in-tree pipeline files (driver, Dockerfile, CMakeLists.txt, rpmbuild/, jenkins-ci-rme/)

A copy of the DEBs is also placed in <pipeline-root>/packages-out/ (same-file skip guarded by device:inode).

Note: --package-output-dir is currently passed through to CMake as an unused variable — the DEB locations above are fixed under the pipeline root, not at --package-output-dir.

Verify a package:

dpkg -c "<pipeline-root>/rpms/guez/26.04/qt6-release-ctest-runtime_1.0-1_amd64.deb" \
  | grep unit_test

Step 5 — CI / Jenkins flow (optional)

The in-tree jenkins-ci-rme/ directory contains the full Jenkins pipeline (Jenkinsfile, builder, publisher) adapted to this tree. Note: it is still wired to the legacy new_docker_build.sh driver and has not been switched to new_docker_build_release2.sh yet. See jenkins-ci-rme/README.md for the pipeline details.

Step 6 — Code coverage (lcov)

--run-coverage is available and is mutually exclusive with --run-jenkins-builder. In the current tree it only passes -DRUN_COVERAGE=ON / -DCOVERAGE_OUTPUT_DIR to the configure — those variables are not consumed by any CMakeLists.txt yet, so no lcov data is collected. The option is kept for the (still to be wired) coverage step.

Options reference

./new_docker_build_release2.sh --help prints the full option list. The main ones:

Option Default Purpose
--group1 / --no-group1 ON DDS middleware group (AP4)
--group3 / --no-group3 ON Lts services + core stack (AP3)
--group5 / --no-group5 ON Viewer tools (AP9)
--group6 / --no-group6 ON Generators (AP9)
--no-ctest — skip the ctest step
--tests-only — see Known quirks
--use-prebuilt-image / --no-prebuilt-image off prebuilt image mode (--docker-image turns it on)
--docker-image IMAGE qt6-migrated-legatus-release2 image to use (auto-built if missing)
--cmake_build_flags FLAGS — extra -D flags appended to the configure
--docker-mount-root PATH /repo container-side mount root
--run-jenkins-builder off produce the DEB packages (Step 4)
--package-output-dir DIR ./packages-out pass-through (see Step 4 note)
--lts-version / --project / --build-number / --build-tag 1.0 / guez / 1 / manual-build package metadata
--run-coverage off coverage flag pass-through (Step 6)
--coverage-output-dir DIR ./coverage-out pass-through (see Step 6)

Environment overrides: BUILD_GROUP1/3/5/6, RUN_CTEST, TESTS_ONLY, USE_PREBUILT_IMAGE, DOCKER_IMAGE, CMAKE_BUILD_FLAGS, DOCKER_MOUNT_ROOT, GUEZ_MODE, RUN_JENKINS_BUILDER, PACKAGE_OUTPUT_DIR, LTS_VERSION, PROJECT, BUILD_NUMBER, BUILD_TAG, RUN_COVERAGE, COVERAGE_OUTPUT_DIR, MIGRATE_PIPELINE_ROOT.

Troubleshooting

  • "Manually-specified variables were not used" at configure — expected. The driver passes packaging/coverage variables (BUILD_GROUP1/3/5/6, RUN_JENKINS_BUILDER, PACKAGE_OUTPUT_DIR, PROJECT, BUILD_NUMBER, BUILD_TAG, RUN_COVERAGE, COVERAGE_OUTPUT_DIR) that no CMakeLists.txt reads yet. BUILD_RTI is consumed.
  • "no Qt platform plugin could be initialized" when running a test binary by hand → export QT_QPA_PLATFORM=offscreen (plus the QT_PLUGIN_PATH from Step 3).
  • GrantleeParserSmoke: ktexttemplate_defaulttags not found → run ctest/tests with the system plugin dir prepended (Step 3).
  • Stale build tree → the driver always recreates ../build/; for manual builds delete ../build/ and rerun Step 2 if CMake behaves oddly.
  • ctest "No tests were found" → the pipeline root was mounted at a different path than the configure used; the build tree embeds absolute paths.
  • Wrong pipeline root → the driver mounts MIGRATE_PIPELINE_ROOT at /repo; it must be the directory that contains qt-migration-legatus/, not the tree itself.
  • rti_license.dat not found → GROUP1 (DDS) requires the license; it is checked in at the tree root (or place it at the pipeline root).

Known quirks

  • --tests-only is documented in --help as "run only ctest, skip all build groups", but the current implementation only skips the ctest step; the group builds still run.
  • The legacy driver new_docker_build.sh (validation scope) is kept in the tree and is still used by jenkins-ci-rme/; its in-tree Dockerfile recipe does not include libbz2-dev (BZip2), which the Release 2 driver's built-in recipe does.