- new_docker_build.sh: the default coverage report location is now qt6-after/build/coverage/<project>/<os>/ (inside the build tree, wiped with it on every run). - README.md: new 'Manual commands (without the driver)' section with the exact image build, container start, from-zero cmake/ninja compile, ctest and instrumented lcov coverage pipeline; Step 6 and the options table updated to the new report location. - Verified end to end: clean from-zero --run-coverage run, 22/22 tests, 122 production files, host-side paths in all artifacts.
19 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-imageforces a rebuild (also bundled into theqt6-release-build-pipelineDEB)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 ownREADME.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
- Docker available on the host.
- A
.envrcin this directory definingMIGRATE_PIPELINE_ROOT— the pipeline root, i.e. the directory that containsqt-migration-legatus/. The driver mounts it at/repoin 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/buildin the container, which is../buildnext 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:
-
Validates the environment (
.envrc,MIGRATE_PIPELINE_ROOT,rti_license.datfor GROUP1) and starts a container with-v ${MIGRATE_PIPELINE_ROOT}:/repoand working directory/repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus. -
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) -
Builds the 61 group targets in order (GROUP1 → GROUP3 → GROUP5 → GROUP6).
-
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 inside the build tree (default:
qt6-after/build/coverage/<PROJECT>/<OS_VERSION>/, e.g.
qt6-after/build/coverage/guez/26.04/); like the build itself, it is
wiped at the start of every driver run:
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.
Manual commands (without the driver)
Everything the driver does, by hand. PIPELINE_ROOT is the directory
that contains qt-migration-legatus/ (the driver mounts it as /repo).
1. Build the image
cd qt-migration-legatus/qt6-after/qt6-migrated-legatus # the tree
docker build -t legatus-qt6:1.0 -f Dockerfile .
2. Start the container
PIPELINE_ROOT=/home/nkana/release_2/qt6-migration-pipeline
docker run --rm -it \
-v "${PIPELINE_ROOT}":/repo \
-w /repo/qt-migration-legatus/qt6-after/qt6-migrated-legatus \
legatus-qt6:1.0 /bin/bash
3. Compile from zero (inside the container)
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 \
.
cmake --build ../build -j$(nproc)
(the driver builds the 61 Release 2 targets one by one instead of the
default all target, for finer progress logs and fail-fast — see the
GROUP*_TARGETS arrays in new_docker_build.sh)
4. Run the tests
cd ../build
export QT_QPA_PLATFORM=offscreen
export QT_PLUGIN_PATH="/usr/lib/x86_64-linux-gnu/qt6/plugins"
ctest --output-on-failure -j$(nproc)
5. Coverage (manual)
First reconfigure the build instrumented — add these four flags to the
cmake configure in step 3 (then cmake --build ../build -j$(nproc) and
run ctest as in step 4):
-DCMAKE_C_FLAGS_RELWITHDEBINFO="-O0 -g --coverage -DNDEBUG -fPIC" \
-DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O0 -g --coverage -DNDEBUG -fPIC" \
-DCMAKE_EXE_LINKER_FLAGS=--coverage \
-DCMAKE_SHARED_LINKER_FLAGS=--coverage \
Then collect, from the build directory (inside the container):
cd ../build
COV_DIR="$PWD/coverage/guez/26.04"
IGNORE="mismatch,unused,source,category,version,gcov,corrupt,unsupported,inconsistent,count"
rm -rf "$COV_DIR" && mkdir -p "$COV_DIR"
lcov --capture --directory . \
--output-file "$COV_DIR/coverage_raw.info" \
--rc branch_coverage=1 --ignore-errors="$IGNORE"
lcov --extract "$COV_DIR/coverage_raw.info" "/repo/qt-migration-legatus/*" \
--output-file "$COV_DIR/coverage.info" \
--rc branch_coverage=1 --ignore-errors="$IGNORE"
rm -f "$COV_DIR/coverage_raw.info"
lcov --remove "$COV_DIR/coverage.info" \
"*/qt6-after/build/*" "*/unit-test/*" "*/UnitTests/*" \
"*unit_test*" "*/tests/*" \
--output-file "$COV_DIR/_filtered.info" \
--rc branch_coverage=1 --ignore-errors="$IGNORE"
mv -f "$COV_DIR/_filtered.info" "$COV_DIR/coverage.info"
genhtml "$COV_DIR/coverage.info" --output-directory "$COV_DIR/html" \
--branch-coverage --title "Legatus Qt6 Release 2 - code coverage" \
--ignore-errors="$IGNORE"
lcov --summary "$COV_DIR/coverage.info" --rc branch_coverage=1 \
--ignore-errors="$IGNORE" > "$COV_DIR/coverage_summary.txt"
Note: by hand the report keeps the container paths (/repo/...); the
driver additionally rewrites them to the host PIPELINE_ROOT (Step 6).
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 |
qt6-after/build/coverage/<project>/<os> |
report dir (inside the build tree) — 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 noCMakeLists.txtreads yet.BUILD_RTIis consumed. - "no Qt platform plugin could be initialized" when running a test
binary by hand →
export QT_QPA_PLATFORM=offscreen(plus theQT_PLUGIN_PATHfrom Step 3). GrantleeParserSmoke:ktexttemplate_defaulttagsnot found → run ctest/tests with the system plugin dir prepended (Step 3).- Coverage build fails to link with
undefined referencetoDTC::GenericDtcSC<...>::readAlive(...)etc. — a call to a pure virtual function only links at-O1and above (GCC rewrites it to__cxa_pure_virtual); at-O0the raw symbol stays undefined. This was triggered by the one-line forwarders inLts/DDS/DTC/generic_dtc.h, which have been removed: the concrete classes ingeneric_dtc_impl.himplement every methodfinal, 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_ROOTat/repo; it must be the directory that containsqt-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-onlyis documented in--helpas "run only ctest, skip all build groups", but the current implementation only skips the ctest step; the group builds still run.