# 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` 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.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 | 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.