Files
qt-migration-legatus/qt6-after/qt6-migrated-legatus/README.md
T
berrux-dev 363bde9a0e Exclude test sources and generated artifacts from the coverage report
- new_docker_build.sh: after the lcov extract step, a --remove step drops
  the unit/smoke test sources (unit-test/, UnitTests/, tests/, *unit_test*)
  and the generated build artifacts (qt6-after/build/ autogen and moc
  files), so the report measures production code only (122 files instead
  of 197).
- README.md: document the exclusions in Step 6.
2026-11-20 10:57:04 +01:00

15 KiB

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.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.sh — build driver (compile, ctest, DEB packaging)
  • rpmbuild/make_rpm_ubuntu26_release2.py — in-tree DEB package producer (self-contained)
  • Dockerfile — the image recipe (single source of truth); the driver builds the image from it when the image is missing or when --no-prebuilt-image forces a rebuild (also bundled into the qt6-release-build-pipeline DEB)
  • 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.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 the in-tree ./Dockerfile (Ubuntu 26.04 base, apt deps, Qt 6.10.2 via aqtinstall, KDReports from source) and continues with the build. --no-prebuilt-image forces a (re)build of the image from ./Dockerfile before running. The default image name is legatus-qt6:1.0. 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.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.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; the in-tree flow calls new_docker_build.sh (the Release 2 driver). See jenkins-ci-rme/README.md for the pipeline details.

Step 6 — Code coverage (lcov)

--run-coverage builds the whole Release 2 scope instrumented (-O0 -g --coverage, overriding the RelWithDebInfo flags), runs the ctest suite and collects an lcov report inside the container (lcov + genhtml ship in the legatus-qt6:1.0 image):

./new_docker_build.sh --run-coverage

The report is written to <pipeline-root>/coverage/<PROJECT>/<OS_VERSION>/ (default: coverage/guez/26.04/), next to qt-migration-legatus/ and outside the tree:

  • html/index.html — browser report (line + branch coverage)
  • coverage.info — lcov tracefile: production code only. Test sources (unit-test/, UnitTests/, tests/, *unit_test*) and generated build artifacts (qt6-after/build/ autogen/moc) are removed after the extract step.
  • coverage_summary.txt — totals (line / branch hit rate)

Source paths inside coverage.info and the html report are rewritten to host paths at the end of the collection (the container mount prefix is replaced by the pipeline root), so the report works directly on the host. Note: the files are created by root inside the container — read them as-is, or chown the directory on the host to edit/move it.

--coverage-output-dir DIR moves the report; DIR must be an absolute path under the pipeline root (relative values are ignored and the default above is used). The option is mutually exclusive with --run-jenkins-builder.

Options reference

./new_docker_build.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 on use the image (build from ./Dockerfile if missing) / force a rebuild from ./Dockerfile
--docker-image IMAGE legatus-qt6:1.0 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 instrument with -O0 --coverage, run ctest, collect the lcov report (Step 6); mutually exclusive with --run-jenkins-builder
--coverage-output-dir DIR <pipeline-root>/coverage/<project>/<os> report dir — only absolute paths under the pipeline root are honored (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).
  • Coverage build fails to link with undefined reference to DTC::GenericDtcSC<...>::readAlive(...) etc. — a call to a pure virtual function only links at -O1 and above (GCC rewrites it to __cxa_pure_virtual); at -O0 the raw symbol stays undefined. This was triggered by the one-line forwarders in Lts/DDS/DTC/generic_dtc.h, which have been removed: the concrete classes in generic_dtc_impl.h implement every method final, so the forwarders were dead code (and a latent infinite recursion).
  • 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.