# 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 -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) ```bash ./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 ```bash ./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: ```bash 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/`: ```bash 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: ```bash 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 `cd`s 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: ```bash 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 ```bash ./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 `/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 `/rpms///`: | 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 `/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: ```bash dpkg -c "/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): ```bash ./new_docker_build.sh --run-coverage ``` The report is written inside the build tree (default: `qt6-after/build/coverage///`, 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 ```bash cd qt-migration-legatus/qt6-after/qt6-migrated-legatus # the tree docker build -t legatus-qt6:1.0 -f Dockerfile . ``` ### 2. Start the container ```bash 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) ```bash 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 ```bash 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): ```bash -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): ```bash 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//` | 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 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.